comparing f220cd3e9daa3362fc5ac81c5feb4a56133cde9e and master on julien.rbrt.fr/tangled-core

+79 -20

api/tangled/cbor_gen.go

···

       7934
       7934
        
       	}

     

       7935
       7935
        
       

     

       7936
       7936
        
       	cw := cbg.NewCborWriter(w)

     

       7937
       7937
       -
       	fieldCount := 9

     

       7937
       7937
       +
       	fieldCount := 10

     

       7938
       7938
        
       

     

       7939
       7939
        
       	if t.Body == nil {

     

       7940
       7940
        
       		fieldCount--

     

       7941
       7941
        
       	}

     

       7942
       7942
        
       

     

       7943
       7943
        
       	if t.Mentions == nil {

     

       7944
       7944
       +
       		fieldCount--

     

       7945
       7945
       +
       	}

     

       7946
       7946
       +
       

     

       7947
       7947
       +
       	if t.Patch == nil {

     

       7944
       7948
        
       		fieldCount--

     

       7945
       7949
        
       	}

     

       7946
       7950
        
       

     
···

       8008
       8012
        
       	}

     

       8009
       8013
        
       

     

       8010
       8014
        
       	// t.Patch (string) (string)

     

       8011
       8011
       -
       	if len("patch") > 1000000 {

     

       8012
       8012
       -
       		return xerrors.Errorf("Value in field \"patch\" was too long")

     

       8013
       8013
       -
       	}

     

       8015
       8015
       +
       	if t.Patch != nil {

     

       8014
       8016
        
       

     

       8015
       8015
       -
       	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len("patch"))); err != nil {

     

       8016
       8016
       -
       		return err

     

       8017
       8017
       -
       	}

     

       8018
       8018
       -
       	if _, err := cw.WriteString(string("patch")); err != nil {

     

       8019
       8019
       -
       		return err

     

       8020
       8020
       -
       	}

     

       8017
       8017
       +
       		if len("patch") > 1000000 {

     

       8018
       8018
       +
       			return xerrors.Errorf("Value in field \"patch\" was too long")

     

       8019
       8019
       +
       		}

     

       8021
       8020
        
       

     

       8022
       8022
       -
       	if len(t.Patch) > 1000000 {

     

       8023
       8023
       -
       		return xerrors.Errorf("Value in field t.Patch was too long")

     

       8024
       8024
       -
       	}

     

       8021
       8021
       +
       		if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len("patch"))); err != nil {

     

       8022
       8022
       +
       			return err

     

       8023
       8023
       +
       		}

     

       8024
       8024
       +
       		if _, err := cw.WriteString(string("patch")); err != nil {

     

       8025
       8025
       +
       			return err

     

       8026
       8026
       +
       		}

     

       8027
       8027
       +
       

     

       8028
       8028
       +
       		if t.Patch == nil {

     

       8029
       8029
       +
       			if _, err := cw.Write(cbg.CborNull); err != nil {

     

       8030
       8030
       +
       				return err

     

       8031
       8031
       +
       			}

     

       8032
       8032
       +
       		} else {

     

       8033
       8033
       +
       			if len(*t.Patch) > 1000000 {

     

       8034
       8034
       +
       				return xerrors.Errorf("Value in field t.Patch was too long")

     

       8035
       8035
       +
       			}

     

       8025
       8036
        
       

     

       8026
       8026
       -
       	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len(t.Patch))); err != nil {

     

       8027
       8027
       -
       		return err

     

       8028
       8028
       -
       	}

     

       8029
       8029
       -
       	if _, err := cw.WriteString(string(t.Patch)); err != nil {

     

       8030
       8030
       -
       		return err

     

       8037
       8037
       +
       			if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len(*t.Patch))); err != nil {

     

       8038
       8038
       +
       				return err

     

       8039
       8039
       +
       			}

     

       8040
       8040
       +
       			if _, err := cw.WriteString(string(*t.Patch)); err != nil {

     

       8041
       8041
       +
       				return err

     

       8042
       8042
       +
       			}

     

       8043
       8043
       +
       		}

     

       8031
       8044
        
       	}

     

       8032
       8045
        
       

     

       8033
       8046
        
       	// t.Title (string) (string)

     
···

       8147
       8160
        
       		return err

     

       8148
       8161
        
       	}

     

       8149
       8162
        
       

     

       8163
       8163
       +
       	// t.PatchBlob (util.LexBlob) (struct)

     

       8164
       8164
       +
       	if len("patchBlob") > 1000000 {

     

       8165
       8165
       +
       		return xerrors.Errorf("Value in field \"patchBlob\" was too long")

     

       8166
       8166
       +
       	}

     

       8167
       8167
       +
       

     

       8168
       8168
       +
       	if err := cw.WriteMajorTypeHeader(cbg.MajTextString, uint64(len("patchBlob"))); err != nil {

     

       8169
       8169
       +
       		return err

     

       8170
       8170
       +
       	}

     

       8171
       8171
       +
       	if _, err := cw.WriteString(string("patchBlob")); err != nil {

     

       8172
       8172
       +
       		return err

     

       8173
       8173
       +
       	}

     

       8174
       8174
       +
       

     

       8175
       8175
       +
       	if err := t.PatchBlob.MarshalCBOR(cw); err != nil {

     

       8176
       8176
       +
       		return err

     

       8177
       8177
       +
       	}

     

       8178
       8178
       +
       

     

       8150
       8179
        
       	// t.References ([]string) (slice)

     

       8151
       8180
        
       	if t.References != nil {

     

       8152
       8181
        
       

     
···

       8262
       8291
        
       		case "patch":

     

       8263
       8292
        
       

     

       8264
       8293
        
       			{

     

       8265
       8265
       -
       				sval, err := cbg.ReadStringWithMax(cr, 1000000)

     

       8294
       8294
       +
       				b, err := cr.ReadByte()

     

       8266
       8295
        
       				if err != nil {

     

       8267
       8296
        
       					return err

     

       8268
       8297
        
       				}

     

       8298
       8298
       +
       				if b != cbg.CborNull[0] {

     

       8299
       8299
       +
       					if err := cr.UnreadByte(); err != nil {

     

       8300
       8300
       +
       						return err

     

       8301
       8301
       +
       					}

     

       8269
       8302
        
       

     

       8270
       8270
       -
       				t.Patch = string(sval)

     

       8303
       8303
       +
       					sval, err := cbg.ReadStringWithMax(cr, 1000000)

     

       8304
       8304
       +
       					if err != nil {

     

       8305
       8305
       +
       						return err

     

       8306
       8306
       +
       					}

     

       8307
       8307
       +
       

     

       8308
       8308
       +
       					t.Patch = (*string)(&sval)

     

       8309
       8309
       +
       				}

     

       8271
       8310
        
       			}

     

       8272
       8311
        
       			// t.Title (string) (string)

     

       8273
       8312
        
       		case "title":

     
···

       8370
       8409
        
       				}

     

       8371
       8410
        
       

     

       8372
       8411
        
       				t.CreatedAt = string(sval)

     

       8412
       8412
       +
       			}

     

       8413
       8413
       +
       			// t.PatchBlob (util.LexBlob) (struct)

     

       8414
       8414
       +
       		case "patchBlob":

     

       8415
       8415
       +
       

     

       8416
       8416
       +
       			{

     

       8417
       8417
       +
       

     

       8418
       8418
       +
       				b, err := cr.ReadByte()

     

       8419
       8419
       +
       				if err != nil {

     

       8420
       8420
       +
       					return err

     

       8421
       8421
       +
       				}

     

       8422
       8422
       +
       				if b != cbg.CborNull[0] {

     

       8423
       8423
       +
       					if err := cr.UnreadByte(); err != nil {

     

       8424
       8424
       +
       						return err

     

       8425
       8425
       +
       					}

     

       8426
       8426
       +
       					t.PatchBlob = new(util.LexBlob)

     

       8427
       8427
       +
       					if err := t.PatchBlob.UnmarshalCBOR(cr); err != nil {

     

       8428
       8428
       +
       						return xerrors.Errorf("unmarshaling t.PatchBlob pointer: %w", err)

     

       8429
       8429
       +
       					}

     

       8430
       8430
       +
       				}

     

       8431
       8431
       +
       

     

       8373
       8432
        
       			}

     

       8374
       8433
        
       			// t.References ([]string) (slice)

     

       8375
       8434
        
       		case "references":

+12 -9

api/tangled/repopull.go

···

       17
       17
        
       } //

     

       18
       18
        
       // RECORDTYPE: RepoPull

     

       19
       19
        
       type RepoPull struct {

     

       20
       20
       -
       	LexiconTypeID string           `json:"$type,const=sh.tangled.repo.pull" cborgen:"$type,const=sh.tangled.repo.pull"`

     

       21
       21
       -
       	Body          *string          `json:"body,omitempty" cborgen:"body,omitempty"`

     

       22
       22
       -
       	CreatedAt     string           `json:"createdAt" cborgen:"createdAt"`

     

       23
       23
       -
       	Mentions      []string         `json:"mentions,omitempty" cborgen:"mentions,omitempty"`

     

       24
       24
       -
       	Patch         string           `json:"patch" cborgen:"patch"`

     

       25
       25
       -
       	References    []string         `json:"references,omitempty" cborgen:"references,omitempty"`

     

       26
       26
       -
       	Source        *RepoPull_Source `json:"source,omitempty" cborgen:"source,omitempty"`

     

       27
       27
       -
       	Target        *RepoPull_Target `json:"target" cborgen:"target"`

     

       28
       28
       -
       	Title         string           `json:"title" cborgen:"title"`

     

       20
       20
       +
       	LexiconTypeID string   `json:"$type,const=sh.tangled.repo.pull" cborgen:"$type,const=sh.tangled.repo.pull"`

     

       21
       21
       +
       	Body          *string  `json:"body,omitempty" cborgen:"body,omitempty"`

     

       22
       22
       +
       	CreatedAt     string   `json:"createdAt" cborgen:"createdAt"`

     

       23
       23
       +
       	Mentions      []string `json:"mentions,omitempty" cborgen:"mentions,omitempty"`

     

       24
       24
       +
       	// patch: (deprecated) use patchBlob instead

     

       25
       25
       +
       	Patch *string `json:"patch,omitempty" cborgen:"patch,omitempty"`

     

       26
       26
       +
       	// patchBlob: patch content

     

       27
       27
       +
       	PatchBlob  *util.LexBlob    `json:"patchBlob" cborgen:"patchBlob"`

     

       28
       28
       +
       	References []string         `json:"references,omitempty" cborgen:"references,omitempty"`

     

       29
       29
       +
       	Source     *RepoPull_Source `json:"source,omitempty" cborgen:"source,omitempty"`

     

       30
       30
       +
       	Target     *RepoPull_Target `json:"target" cborgen:"target"`

     

       31
       31
       +
       	Title      string           `json:"title" cborgen:"title"`

     

       29
       32
        
       }

     

       30
       33
        
       

     

       31
       34
        
       // RepoPull_Source is a "source" in the sh.tangled.repo.pull schema.

appview/db/follow.go

···

       167
       167
        
       	if err != nil {

     

       168
       168
        
       		return nil, err

     

       169
       169
        
       	}

     

       170
       170
       +
       	defer rows.Close()

     

       171
       171
       +
       

     

       170
       172
        
       	for rows.Next() {

     

       171
       173
        
       		var follow models.Follow

     

       172
       174
        
       		var followedAt string

appview/db/issues.go

···

       452
       452
        
       	if err != nil {

     

       453
       453
        
       		return nil, err

     

       454
       454
        
       	}

     

       455
       455
       +
       	defer rows.Close()

     

       455
       456
        
       

     

       456
       457
        
       	for rows.Next() {

     

       457
       458
        
       		var comment models.IssueComment

+1 -1

appview/db/language.go

···

       28
       28
        
       		whereClause,

     

       29
       29
        
       	)

     

       30
       30
        
       	rows, err := e.Query(query, args...)

     

       31
       31
       -
       

     

       32
       31
        
       	if err != nil {

     

       33
       32
        
       		return nil, fmt.Errorf("failed to execute query: %w ", err)

     

       34
       33
        
       	}

     

       34
       34
       +
       	defer rows.Close()

     

       35
       35
        
       

     

       36
       36
        
       	var langs []models.RepoLanguage

     

       37
       37
        
       	for rows.Next() {

appview/db/profile.go

···

       230
       230
        
       	if err != nil {

     

       231
       231
        
       		return nil, err

     

       232
       232
        
       	}

     

       233
       233
       +
       	defer rows.Close()

     

       233
       234
        
       

     

       234
       235
        
       	profileMap := make(map[string]*models.Profile)

     

       235
       236
        
       	for rows.Next() {

     
···

       270
       271
        
       	if err != nil {

     

       271
       272
        
       		return nil, err

     

       272
       273
        
       	}

     

       274
       274
       +
       	defer rows.Close()

     

       275
       275
       +
       

     

       273
       276
        
       	idxs := make(map[string]int)

     

       274
       277
        
       	for did := range profileMap {

     

       275
       278
        
       		idxs[did] = 0

     
···

       290
       293
        
       	if err != nil {

     

       291
       294
        
       		return nil, err

     

       292
       295
        
       	}

     

       296
       296
       +
       	defer rows.Close()

     

       297
       297
       +
       

     

       293
       298
        
       	idxs = make(map[string]int)

     

       294
       299
        
       	for did := range profileMap {

     

       295
       300
        
       		idxs[did] = 0

appview/db/registration.go

···

       38
       38
        
       	if err != nil {

     

       39
       39
        
       		return nil, err

     

       40
       40
        
       	}

     

       41
       41
       +
       	defer rows.Close()

     

       41
       42
        
       

     

       42
       43
        
       	for rows.Next() {

     

       43
       44
        
       		var createdAt string

+12 -1

appview/db/repos.go

···

       56
       56
        
       		limitClause,

     

       57
       57
        
       	)

     

       58
       58
        
       	rows, err := e.Query(repoQuery, args...)

     

       59
       59
       -
       

     

       60
       59
        
       	if err != nil {

     

       61
       60
        
       		return nil, fmt.Errorf("failed to execute repo query: %w ", err)

     

       62
       61
        
       	}

     

       62
       62
       +
       	defer rows.Close()

     

       63
       63
        
       

     

       64
       64
        
       	for rows.Next() {

     

       65
       65
        
       		var repo models.Repo

     
···

       128
       128
        
       	if err != nil {

     

       129
       129
        
       		return nil, fmt.Errorf("failed to execute labels query: %w ", err)

     

       130
       130
        
       	}

     

       131
       131
       +
       	defer rows.Close()

     

       132
       132
       +
       

     

       131
       133
        
       	for rows.Next() {

     

       132
       134
        
       		var repoat, labelat string

     

       133
       135
        
       		if err := rows.Scan(&repoat, &labelat); err != nil {

     
···

       156
       158
        
       			from repo_languages

     

       157
       159
        
       			where repo_at in (%s)

     

       158
       160
        
       			and is_default_ref = 1

     

       161
       161
       +
       			and language <> ''

     

       159
       162
        
       		)

     

       160
       163
        
       		where rn = 1

     

       161
       164
        
       		`,

     
···

       165
       168
        
       	if err != nil {

     

       166
       169
        
       		return nil, fmt.Errorf("failed to execute lang query: %w ", err)

     

       167
       170
        
       	}

     

       171
       171
       +
       	defer rows.Close()

     

       172
       172
       +
       

     

       168
       173
        
       	for rows.Next() {

     

       169
       174
        
       		var repoat, lang string

     

       170
       175
        
       		if err := rows.Scan(&repoat, &lang); err != nil {

     
···

       191
       196
        
       	if err != nil {

     

       192
       197
        
       		return nil, fmt.Errorf("failed to execute star-count query: %w ", err)

     

       193
       198
        
       	}

     

       199
       199
       +
       	defer rows.Close()

     

       200
       200
       +
       

     

       194
       201
        
       	for rows.Next() {

     

       195
       202
        
       		var repoat string

     

       196
       203
        
       		var count int

     
···

       220
       227
        
       	if err != nil {

     

       221
       228
        
       		return nil, fmt.Errorf("failed to execute issue-count query: %w ", err)

     

       222
       229
        
       	}

     

       230
       230
       +
       	defer rows.Close()

     

       231
       231
       +
       

     

       223
       232
        
       	for rows.Next() {

     

       224
       233
        
       		var repoat string

     

       225
       234
        
       		var open, closed int

     
···

       261
       270
        
       	if err != nil {

     

       262
       271
        
       		return nil, fmt.Errorf("failed to execute pulls-count query: %w ", err)

     

       263
       272
        
       	}

     

       273
       273
       +
       	defer rows.Close()

     

       274
       274
       +
       

     

       264
       275
        
       	for rows.Next() {

     

       265
       276
        
       		var repoat string

     

       266
       277
        
       		var open, merged, closed, deleted int

appview/db/star.go

···

       165
       165
        
       	if err != nil {

     

       166
       166
        
       		return nil, err

     

       167
       167
        
       	}

     

       168
       168
       +
       	defer rows.Close()

     

       168
       169
        
       

     

       169
       170
        
       	starMap := make(map[string][]models.Star)

     

       170
       171
        
       	for rows.Next() {

+1 -1

appview/models/pull.go

···

       83
       83
        
       	Repo   *Repo

     

       84
       84
        
       }

     

       85
       85
        
       

     

       86
       86
       +
       // NOTE: This method does not include patch blob in returned atproto record

     

       86
       87
        
       func (p Pull) AsRecord() tangled.RepoPull {

     

       87
       88
        
       	var source *tangled.RepoPull_Source

     

       88
       89
        
       	if p.PullSource != nil {

     
···

       113
       114
        
       			Repo:   p.RepoAt.String(),

     

       114
       115
        
       			Branch: p.TargetBranch,

     

       115
       116
        
       		},

     

       116
       116
       -
       		Patch:  p.LatestPatch(),

     

       117
       117
        
       		Source: source,

     

       118
       118
        
       	}

     

       119
       119
        
       	return record

-1

appview/notify/merged_notifier.go

···

       39
       39
        
       			v.Call(in)

     

       40
       40
        
       		}(n)

     

       41
       41
        
       	}

     

       42
       42
       -
       	wg.Wait()

     

       43
       42
        
       }

     

       44
       43
        
       

     

       45
       44
        
       func (m *mergedNotifier) NewRepo(ctx context.Context, repo *models.Repo) {

+6 -1

appview/pages/funcmap.go

···

       25
       25
        
       	"github.com/dustin/go-humanize"

     

       26
       26
        
       	"github.com/go-enry/go-enry/v2"

     

       27
       27
        
       	"github.com/yuin/goldmark"

     

       28
       28
       +
       	emoji "github.com/yuin/goldmark-emoji"

     

       28
       29
        
       	"tangled.org/core/appview/filetree"

     

       29
       30
        
       	"tangled.org/core/appview/models"

     

       30
       31
        
       	"tangled.org/core/appview/pages/markup"

     
···

       261
       262
        
       		},

     

       262
       263
        
       		"description": func(text string) template.HTML {

     

       263
       264
        
       			p.rctx.RendererType = markup.RendererTypeDefault

     

       264
       264
       -
       			htmlString := p.rctx.RenderMarkdownWith(text, goldmark.New())

     

       265
       265
       +
       			htmlString := p.rctx.RenderMarkdownWith(text, goldmark.New(

     

       266
       266
       +
       				goldmark.WithExtensions(

     

       267
       267
       +
       					emoji.Emoji,

     

       268
       268
       +
       				),

     

       269
       269
       +
       			))

     

       265
       270
        
       			sanitized := p.rctx.SanitizeDescription(htmlString)

     

       266
       271
        
       			return template.HTML(sanitized)

     

       267
       272
        
       		},

+13 -3

appview/pages/markup/extension/atlink.go

···

       35
       35
        
       	return KindAt

     

       36
       36
        
       }

     

       37
       37
        
       

     

       38
       38
       -
       var atRegexp = regexp.MustCompile(`(^|\s|\()(@)([a-zA-Z0-9.-]+)(\b)`)

     

       38
       38
       +
       var atRegexp = regexp.MustCompile(`(^|\s|\()(@)([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\b)`)

     

       39
       39
       +
       var markdownLinkRegexp = regexp.MustCompile(`(?ms)\[.*\]\(.*\)`)

     

       39
       40
        
       

     

       40
       41
        
       type atParser struct{}

     

       41
       42
        
       

     
···

       55
       56
        
       	if m == nil {

     

       56
       57
        
       		return nil

     

       57
       58
        
       	}

     

       59
       59
       +
       

     

       60
       60
       +
       	// Check for all links in the markdown to see if the handle found is inside one

     

       61
       61
       +
       	linksIndexes := markdownLinkRegexp.FindAllIndex(block.Source(), -1)

     

       62
       62
       +
       	for _, linkMatch := range linksIndexes {

     

       63
       63
       +
       		if linkMatch[0] < segment.Start && segment.Start < linkMatch[1] {

     

       64
       64
       +
       			return nil

     

       65
       65
       +
       		}

     

       66
       66
       +
       	}

     

       67
       67
       +
       

     

       58
       68
        
       	atSegment := text.NewSegment(segment.Start, segment.Start+m[1])

     

       59
       69
        
       	block.Advance(m[1])

     

       60
       70
        
       	node := &AtNode{}

     
···

       87
       97
        
       

     

       88
       98
        
       func (r *atHtmlRenderer) renderAt(w util.BufWriter, source []byte, n ast.Node, entering bool) (ast.WalkStatus, error) {

     

       89
       99
        
       	if entering {

     

       90
       90
       -
       		w.WriteString(`<a href="/@`)

     

       100
       100
       +
       		w.WriteString(`<a href="/`)

     

       91
       101
        
       		w.WriteString(n.(*AtNode).Handle)

     

       92
       92
       -
       		w.WriteString(`" class="mention font-bold">`)

     

       102
       102
       +
       		w.WriteString(`" class="mention">`)

     

       93
       103
        
       	} else {

     

       94
       104
        
       		w.WriteString("</a>")

     

       95
       105
        
       	}

appview/pages/markup/markdown.go

···

       13
       13
        
       	chromahtml "github.com/alecthomas/chroma/v2/formatters/html"

     

       14
       14
        
       	"github.com/alecthomas/chroma/v2/styles"

     

       15
       15
        
       	"github.com/yuin/goldmark"

     

       16
       16
       +
       	"github.com/yuin/goldmark-emoji"

     

       16
       17
        
       	highlighting "github.com/yuin/goldmark-highlighting/v2"

     

       17
       18
        
       	"github.com/yuin/goldmark/ast"

     

       18
       19
        
       	"github.com/yuin/goldmark/extension"

     
···

       66
       67
        
       			),

     

       67
       68
        
       			callout.CalloutExtention,

     

       68
       69
        
       			textension.AtExt,

     

       70
       70
       +
       			emoji.Emoji,

     

       69
       71
        
       		),

     

       70
       72
        
       		goldmark.WithParserOptions(

     

       71
       73
        
       			parser.WithAutoHeadingID(),

+121

appview/pages/markup/markdown_test.go

···

       1
       1
       +
       package markup

     

       2
       2
       +
       

     

       3
       3
       +
       import (

     

       4
       4
       +
       	"bytes"

     

       5
       5
       +
       	"testing"

     

       6
       6
       +
       )

     

       7
       7
       +
       

     

       8
       8
       +
       func TestAtExtension_Rendering(t *testing.T) {

     

       9
       9
       +
       	tests := []struct {

     

       10
       10
       +
       		name     string

     

       11
       11
       +
       		markdown string

     

       12
       12
       +
       		expected string

     

       13
       13
       +
       	}{

     

       14
       14
       +
       		{

     

       15
       15
       +
       			name:     "renders simple at mention",

     

       16
       16
       +
       			markdown: "Hello @user.tngl.sh!",

     

       17
       17
       +
       			expected: `<p>Hello <a href="/user.tngl.sh" class="mention">@user.tngl.sh</a>!</p>`,

     

       18
       18
       +
       		},

     

       19
       19
       +
       		{

     

       20
       20
       +
       			name:     "renders multiple at mentions",

     

       21
       21
       +
       			markdown: "Hi @alice.tngl.sh and @bob.example.com",

     

       22
       22
       +
       			expected: `<p>Hi <a href="/alice.tngl.sh" class="mention">@alice.tngl.sh</a> and <a href="/bob.example.com" class="mention">@bob.example.com</a></p>`,

     

       23
       23
       +
       		},

     

       24
       24
       +
       		{

     

       25
       25
       +
       			name:     "renders at mention in parentheses",

     

       26
       26
       +
       			markdown: "Check this out (@user.tngl.sh)",

     

       27
       27
       +
       			expected: `<p>Check this out (<a href="/user.tngl.sh" class="mention">@user.tngl.sh</a>)</p>`,

     

       28
       28
       +
       		},

     

       29
       29
       +
       		{

     

       30
       30
       +
       			name:     "does not render email",

     

       31
       31
       +
       			markdown: "Contact me at test@example.com",

     

       32
       32
       +
       			expected: `<p>Contact me at <a href="mailto:test@example.com">test@example.com</a></p>`,

     

       33
       33
       +
       		},

     

       34
       34
       +
       		{

     

       35
       35
       +
       			name:     "renders at mention with hyphen",

     

       36
       36
       +
       			markdown: "Follow @user-name.tngl.sh",

     

       37
       37
       +
       			expected: `<p>Follow <a href="/user-name.tngl.sh" class="mention">@user-name.tngl.sh</a></p>`,

     

       38
       38
       +
       		},

     

       39
       39
       +
       		{

     

       40
       40
       +
       			name:     "renders at mention with numbers",

     

       41
       41
       +
       			markdown: "@user123.test456.social",

     

       42
       42
       +
       			expected: `<p><a href="/user123.test456.social" class="mention">@user123.test456.social</a></p>`,

     

       43
       43
       +
       		},

     

       44
       44
       +
       		{

     

       45
       45
       +
       			name:     "at mention at start of line",

     

       46
       46
       +
       			markdown: "@user.tngl.sh is cool",

     

       47
       47
       +
       			expected: `<p><a href="/user.tngl.sh" class="mention">@user.tngl.sh</a> is cool</p>`,

     

       48
       48
       +
       		},

     

       49
       49
       +
       	}

     

       50
       50
       +
       

     

       51
       51
       +
       	for _, tt := range tests {

     

       52
       52
       +
       		t.Run(tt.name, func(t *testing.T) {

     

       53
       53
       +
       			md := NewMarkdown()

     

       54
       54
       +
       

     

       55
       55
       +
       			var buf bytes.Buffer

     

       56
       56
       +
       			if err := md.Convert([]byte(tt.markdown), &buf); err != nil {

     

       57
       57
       +
       				t.Fatalf("failed to convert markdown: %v", err)

     

       58
       58
       +
       			}

     

       59
       59
       +
       

     

       60
       60
       +
       			result := buf.String()

     

       61
       61
       +
       			if result != tt.expected+"\n" {

     

       62
       62
       +
       				t.Errorf("expected:\n%s\ngot:\n%s", tt.expected, result)

     

       63
       63
       +
       			}

     

       64
       64
       +
       		})

     

       65
       65
       +
       	}

     

       66
       66
       +
       }

     

       67
       67
       +
       

     

       68
       68
       +
       func TestAtExtension_WithOtherMarkdown(t *testing.T) {

     

       69
       69
       +
       	tests := []struct {

     

       70
       70
       +
       		name     string

     

       71
       71
       +
       		markdown string

     

       72
       72
       +
       		contains string

     

       73
       73
       +
       	}{

     

       74
       74
       +
       		{

     

       75
       75
       +
       			name:     "at mention with bold",

     

       76
       76
       +
       			markdown: "**Hello @user.tngl.sh**",

     

       77
       77
       +
       			contains: `<strong>Hello <a href="/user.tngl.sh" class="mention">@user.tngl.sh</a></strong>`,

     

       78
       78
       +
       		},

     

       79
       79
       +
       		{

     

       80
       80
       +
       			name:     "at mention with italic",

     

       81
       81
       +
       			markdown: "*Check @user.tngl.sh*",

     

       82
       82
       +
       			contains: `<em>Check <a href="/user.tngl.sh" class="mention">@user.tngl.sh</a></em>`,

     

       83
       83
       +
       		},

     

       84
       84
       +
       		{

     

       85
       85
       +
       			name:     "at mention in list",

     

       86
       86
       +
       			markdown: "- Item 1\n- @user.tngl.sh\n- Item 3",

     

       87
       87
       +
       			contains: `<a href="/user.tngl.sh" class="mention">@user.tngl.sh</a>`,

     

       88
       88
       +
       		},

     

       89
       89
       +
       		{

     

       90
       90
       +
       			name:     "at mention in link",

     

       91
       91
       +
       			markdown: "[@regnault.dev](https://regnault.dev)",

     

       92
       92
       +
       			contains: `<a href="https://regnault.dev">@regnault.dev</a>`,

     

       93
       93
       +
       		},

     

       94
       94
       +
       		{

     

       95
       95
       +
       			name:     "at mention in link again",

     

       96
       96
       +
       			markdown: "[check out @regnault.dev](https://regnault.dev)",

     

       97
       97
       +
       			contains: `<a href="https://regnault.dev">check out @regnault.dev</a>`,

     

       98
       98
       +
       		},

     

       99
       99
       +
       		{

     

       100
       100
       +
       			name:     "at mention in link again, multiline",

     

       101
       101
       +
       			markdown: "[\ncheck out @regnault.dev](https://regnault.dev)",

     

       102
       102
       +
       			contains: "<a href=\"https://regnault.dev\">\ncheck out @regnault.dev</a>",

     

       103
       103
       +
       		},

     

       104
       104
       +
       	}

     

       105
       105
       +
       

     

       106
       106
       +
       	for _, tt := range tests {

     

       107
       107
       +
       		t.Run(tt.name, func(t *testing.T) {

     

       108
       108
       +
       			md := NewMarkdown()

     

       109
       109
       +
       

     

       110
       110
       +
       			var buf bytes.Buffer

     

       111
       111
       +
       			if err := md.Convert([]byte(tt.markdown), &buf); err != nil {

     

       112
       112
       +
       				t.Fatalf("failed to convert markdown: %v", err)

     

       113
       113
       +
       			}

     

       114
       114
       +
       

     

       115
       115
       +
       			result := buf.String()

     

       116
       116
       +
       			if !bytes.Contains([]byte(result), []byte(tt.contains)) {

     

       117
       117
       +
       				t.Errorf("expected output to contain:\n%s\ngot:\n%s", tt.contains, result)

     

       118
       118
       +
       			}

     

       119
       119
       +
       		})

     

       120
       120
       +
       	}

     

       121
       121
       +
       }

+1 -1

appview/pages/pages.go

···

       640
       640
        
       }

     

       641
       641
        
       

     

       642
       642
        
       func (p *Pages) StarBtnFragment(w io.Writer, params StarBtnFragmentParams) error {

     

       643
       643
       -
       	return p.executePlain("fragments/starBtn", w, params)

     

       643
       643
       +
       	return p.executePlain("fragments/starBtn-oob", w, params)

     

       644
       644
        
       }

     

       645
       645
        
       

     

       646
       646
        
       type RepoIndexParams struct {

+1 -1

appview/pages/templates/banner.html

···

       30
       30
        
           <div class="mx-6">

     

       31
       31
        
             These services may not be fully accessible until upgraded.

     

       32
       32
        
             <a class="underline text-red-800 dark:text-red-200"

     

       33
       33
       -
               href="https://tangled.org/@tangled.org/core/tree/master/docs/migrations.md">

     

       33
       33
       +
               href="https://docs.tangled.org/migrating-knots-spindles.html#migrating-knots-spindles">

     

       34
       34
        
               Click to read the upgrade guide</a>.

     

       35
       35
        
           </div>

     

       36
       36
        
         </details>

appview/pages/templates/fragments/starBtn-oob.html

···

       1
       1
       +
       {{ define "fragments/starBtn-oob" }}

     

       2
       2
       +
         <div hx-swap-oob='outerHTML:#starBtn[data-star-subject-at="{{ .SubjectAt }}"]'>

     

       3
       3
       +
           {{ template "fragments/starBtn" . }}

     

       4
       4
       +
         </div>

     

       5
       5
       +
       {{ end }}

+1 -3

appview/pages/templates/fragments/starBtn.html

···

       1
       1
        
       {{ define "fragments/starBtn" }}

     

       2
       2
       +
           {{/* NOTE: this fragment is always replaced with hx-swap-oob */}}

     

       2
       3
        
           <button

     

       3
       4
        
               id="starBtn"

     

       4
       5
        
               class="btn disabled:opacity-50 disabled:cursor-not-allowed flex gap-2 items-center group"

     
···

       10
       11
        
               {{ end }}

     

       11
       12
        
       

     

       12
       13
        
               hx-trigger="click"

     

       13
       13
       -
               hx-target="this"

     

       14
       14
       -
               hx-swap="outerHTML"

     

       15
       15
       -
               hx-swap-oob='outerHTML:#starBtn[data-star-subject-at="{{ .SubjectAt }}"]'

     

       16
       14
        
               hx-disabled-elt="#starBtn"

     

       17
       15
        
           >

     

       18
       16
        
               {{ if .IsStarred }}

+1 -1

appview/pages/templates/knots/index.html

···

       105
       105
        
       {{ define "docsButton" }}

     

       106
       106
        
       <a

     

       107
       107
        
       class="btn flex items-center gap-2"

     

       108
       108
       -
       href="https://tangled.org/@tangled.org/core/blob/master/docs/spindle/hosting.md">

     

       108
       108
       +
       href="https://docs.tangled.org/knot-self-hosting-guide.html#knot-self-hosting-guide">

     

       109
       109
        
       {{ i "book" "size-4" }}

     

       110
       110
        
       docs

     

       111
       111
        
       </a>

+2 -2

appview/pages/templates/layouts/fragments/footer.html

···

       26
       26
        
                 <div class="flex flex-col gap-1">

     

       27
       27
        
                   <div class="{{ $headerStyle }}">resources</div>

     

       28
       28
        
                   <a href="https://blog.tangled.org" class="{{ $linkStyle }}" target="_blank" rel="noopener noreferrer">{{ i "book-open" $iconStyle }} blog</a>

     

       29
       29
       -
                   <a href="https://tangled.org/@tangled.org/core/tree/master/docs" class="{{ $linkStyle }}">{{ i "book" $iconStyle }} docs</a>

     

       29
       29
       +
                   <a href="https://docs.tangled.org" class="{{ $linkStyle }}">{{ i "book" $iconStyle }} docs</a>

     

       30
       30
        
                   <a href="https://tangled.org/@tangled.org/core" class="{{ $linkStyle }}">{{ i "code" $iconStyle }} source</a>

     

       31
       31
        
                   <a href="https://tangled.org/brand" class="{{ $linkStyle }}">{{ i "paintbrush" $iconStyle }} brand</a>

     

       32
       32
        
                 </div>

     
···

       73
       73
        
                 <div class="flex flex-col gap-1">

     

       74
       74
        
                   <div class="{{ $headerStyle }}">resources</div>

     

       75
       75
        
                   <a href="https://blog.tangled.org" class="{{ $linkStyle }}" target="_blank" rel="noopener noreferrer">{{ i "book-open" $iconStyle }} blog</a>

     

       76
       76
       -
                   <a href="https://tangled.org/@tangled.org/core/tree/master/docs" class="{{ $linkStyle }}">{{ i "book" $iconStyle }} docs</a>

     

       76
       76
       +
                   <a href="https://docs.tangled.org" class="{{ $linkStyle }}">{{ i "book" $iconStyle }} docs</a>

     

       77
       77
        
                   <a href="https://tangled.org/@tangled.org/core" class="{{ $linkStyle }}">{{ i "code" $iconStyle }} source</a>

     

       78
       78
        
                   <a href="https://tangled.org/brand" class="{{ $linkStyle }}">{{ i "paintbrush" $iconStyle }} brand</a>

     

       79
       79
        
                 </div>

+1 -1

appview/pages/templates/repo/empty.html

···

       26
       26
        
           {{ else if (and .LoggedInUser (eq .LoggedInUser.Did .RepoInfo.OwnerDid)) }}

     

       27
       27
        
             {{ $knot := .RepoInfo.Knot }}

     

       28
       28
        
             {{ if eq $knot "knot1.tangled.sh" }}

     

       29
       29
       -
                 {{ $knot = "tangled.sh" }}

     

       29
       29
       +
                 {{ $knot = "tangled.org" }}

     

       30
       30
        
             {{ end }}

     

       31
       31
        
             <div class="w-full flex place-content-center">

     

       32
       32
        
               <div class="py-6 w-fit flex flex-col gap-4">

+6 -6

appview/pages/templates/repo/fragments/backlinks.html

···

       14
       14
        
                 <div class="flex gap-2 items-center">

     

       15
       15
        
                   {{ if .State.IsClosed }}

     

       16
       16
        
                     <span class="text-gray-500 dark:text-gray-400">

     

       17
       17
       -
                       {{ i "ban" "w-4 h-4" }}

     

       17
       17
       +
                       {{ i "ban" "size-3" }}

     

       18
       18
        
                     </span>

     

       19
       19
        
                   {{ else if eq .Kind.String "issues" }}

     

       20
       20
        
                     <span class="text-green-600 dark:text-green-500">

     

       21
       21
       -
                       {{ i "circle-dot" "w-4 h-4" }}

     

       21
       21
       +
                       {{ i "circle-dot" "size-3" }}

     

       22
       22
        
                     </span>

     

       23
       23
        
                   {{ else if .State.IsOpen }}

     

       24
       24
        
                     <span class="text-green-600 dark:text-green-500">

     

       25
       25
       -
                       {{ i "git-pull-request" "w-4 h-4" }}

     

       25
       25
       +
                       {{ i "git-pull-request" "size-3" }}

     

       26
       26
        
                     </span>

     

       27
       27
        
                   {{ else if .State.IsMerged }}

     

       28
       28
        
                     <span class="text-purple-600 dark:text-purple-500">

     

       29
       29
       -
                       {{ i "git-merge" "w-4 h-4" }}

     

       29
       29
       +
                       {{ i "git-merge" "size-3" }}

     

       30
       30
        
                     </span>

     

       31
       31
        
                   {{ else }}

     

       32
       32
        
                     <span class="text-gray-600 dark:text-gray-300">

     

       33
       33
       -
                       {{ i "git-pull-request-closed" "w-4 h-4" }}

     

       33
       33
       +
                       {{ i "git-pull-request-closed" "size-3" }}

     

       34
       34
        
                     </span>

     

       35
       35
        
                   {{ end }}

     

       36
       36
       -
                   <a href="{{ . }}"><span class="text-gray-500 dark:text-gray-400">#{{ .SubjectId }}</span> {{ .Title }}</a>

     

       36
       36
       +
                   <a href="{{ . }}" class="line-clamp-1 text-sm"><span class="text-gray-500 dark:text-gray-400">#{{ .SubjectId }}</span> {{ .Title }}</a>

     

       37
       37
        
                 </div>

     

       38
       38
        
                 {{ if not (eq $.RepoInfo.FullName $repoUrl) }}

     

       39
       39
        
                 <div>

+1 -1

appview/pages/templates/repo/fragments/diff.html

···

       17
       17
        
           {{ else }}

     

       18
       18
        
           {{ range $idx, $hunk := $diff }}

     

       19
       19
        
             {{ with $hunk }}

     

       20
       20
       -
               <details open id="file-{{ .Name.New }}" class="group border border-gray-200 dark:border-gray-700 w-full mx-auto rounded bg-white dark:bg-gray-800 drop-shadow-sm" tabindex="{{ add $idx 1 }}">

     

       20
       20
       +
               <details open id="file-{{ .Id }}" class="group border border-gray-200 dark:border-gray-700 w-full mx-auto rounded bg-white dark:bg-gray-800 drop-shadow-sm" tabindex="{{ add $idx 1 }}">

     

       21
       21
        
                 <summary class="list-none cursor-pointer sticky top-0">

     

       22
       22
        
                   <div id="diff-file-header" class="rounded cursor-pointer bg-white dark:bg-gray-800 flex justify-between">

     

       23
       23
        
                     <div id="left-side-items" class="p-2 flex gap-2 items-center overflow-x-auto">

+1 -1

appview/pages/templates/repo/pipelines/pipelines.html

···

       23
       23
        
             </p>

     

       24
       24
        
             <p>

     

       25
       25
        
               <span class="{{ $bullet }}">2</span>Configure your CI/CD

     

       26
       26
       -
               <a href="https://tangled.org/@tangled.org/core/blob/master/docs/spindle/pipeline.md" class="underline">pipeline</a>.

     

       26
       26
       +
               <a href="https://docs.tangled.org/spindles.html#pipelines" class="underline">pipeline</a>.

     

       27
       27
        
             </p>

     

       28
       28
        
             <p><span class="{{ $bullet }}">3</span>Trigger a workflow with a push or a pull-request!</p>

     

       29
       29
        
           </div>

+1 -1

appview/pages/templates/repo/settings/pipelines.html

···

       22
       22
        
             <p class="text-gray-500 dark:text-gray-400">

     

       23
       23
        
               Choose a spindle to execute your workflows on. Only repository owners

     

       24
       24
        
               can configure spindles. Spindles can be selfhosted,

     

       25
       25
       -
               <a class="text-gray-500 dark:text-gray-400 underline" href="https://tangled.org/@tangled.org/core/blob/master/docs/spindle/hosting.md">

     

       25
       25
       +
               <a class="text-gray-500 dark:text-gray-400 underline" href="https://docs.tangled.org/spindles.html#self-hosting-guide">

     

       26
       26
        
                 click to learn more.

     

       27
       27
        
               </a>

     

       28
       28
        
             </p>

+1 -1

appview/pages/templates/spindles/index.html

···

       102
       102
        
       {{ define "docsButton" }}

     

       103
       103
        
       <a

     

       104
       104
        
       class="btn flex items-center gap-2"

     

       105
       105
       -
       href="https://tangled.org/@tangled.org/core/blob/master/docs/spindle/hosting.md">

     

       105
       105
       +
       href="https://docs.tangled.org/spindles.html#self-hosting-guide">

     

       106
       106
        
       {{ i "book" "size-4" }}

     

       107
       107
        
       docs

     

       108
       108
        
       </a>

+1 -1

appview/pages/templates/strings/string.html

···

       17
       17
        
               <span class="select-none">/</span>

     

       18
       18
        
               <a href="/strings/{{ $ownerId }}/{{ .String.Rkey }}" class="font-bold">{{ .String.Filename }}</a>

     

       19
       19
        
             </div>

     

       20
       20
       -
             <div class="flex gap-2 text-base">

     

       20
       20
       +
             <div class="flex gap-2 items-stretch text-base">

     

       21
       21
        
               {{ if and .LoggedInUser (eq .LoggedInUser.Did .String.Did) }}

     

       22
       22
        
                 <a class="btn flex items-center gap-2 no-underline hover:no-underline p-2 group"

     

       23
       23
        
                    hx-boost="true"

+2 -2

appview/pages/templates/user/fragments/followCard.html

···

       6
       6
        
             <img class="object-cover rounded-full p-2" src="{{ fullAvatar $userIdent }}" alt="{{ $userIdent }}" />

     

       7
       7
        
           </div>

     

       8
       8
        
       

     

       9
       9
       -
           <div class="flex flex-col md:flex-row md:items-center md:justify-between gap-2 w-full">

     

       9
       9
       +
           <div class="flex flex-col md:flex-row md:items-center md:justify-between gap-2 w-full min-w-0">

     

       10
       10
        
             <div class="flex-1 min-h-0 justify-around flex flex-col">

     

       11
       11
        
               <a href="/{{ $userIdent }}">

     

       12
       12
        
                 <span class="font-bold dark:text-white overflow-hidden text-ellipsis whitespace-nowrap max-w-full">{{ $userIdent | truncateAt30 }}</span>

     

       13
       13
        
               </a>

     

       14
       14
        
               {{ with .Profile }}

     

       15
       15
       -
               <p class="text-sm pb-2 md:pb-2">{{.Description}}</p>

     

       15
       15
       +
               <p class="text-sm pb-2 md:pb-2 break-words">{{.Description}}</p>

     

       16
       16
        
               {{ end }}

     

       17
       17
        
               <div class="text-sm flex items-center gap-2 my-2 overflow-hidden text-ellipsis whitespace-nowrap max-w-full">

     

       18
       18
        
                 <span class="flex-shrink-0">{{ i "users" "size-4" }}</span>

+56 -36

appview/pulls/pulls.go

···

       1241
       1241
        
       		return

     

       1242
       1242
        
       	}

     

       1243
       1243
        
       

     

       1244
       1244
       +
       	blob, err := comatproto.RepoUploadBlob(r.Context(), client, strings.NewReader(patch))

     

       1245
       1245
       +
       	if err != nil {

     

       1246
       1246
       +
       		log.Println("failed to upload patch", err)

     

       1247
       1247
       +
       		s.pages.Notice(w, "pull", "Failed to create pull request. Try again later.")

     

       1248
       1248
       +
       		return

     

       1249
       1249
       +
       	}

     

       1250
       1250
       +
       

     

       1244
       1251
        
       	_, err = comatproto.RepoPutRecord(r.Context(), client, &comatproto.RepoPutRecord_Input{

     

       1245
       1252
        
       		Collection: tangled.RepoPullNSID,

     

       1246
       1253
        
       		Repo:       user.Did,

     
···

       1252
       1259
        
       					Repo:   string(repo.RepoAt()),

     

       1253
       1260
        
       					Branch: targetBranch,

     

       1254
       1261
        
       				},

     

       1255
       1255
       -
       				Patch:     patch,

     

       1262
       1262
       +
       				PatchBlob: blob.Blob,

     

       1256
       1263
        
       				Source:    recordPullSource,

     

       1257
       1264
        
       				CreatedAt: time.Now().Format(time.RFC3339),

     

       1258
       1265
        
       			},

     
···

       1328
       1335
        
       	// apply all record creations at once

     

       1329
       1336
        
       	var writes []*comatproto.RepoApplyWrites_Input_Writes_Elem

     

       1330
       1337
        
       	for _, p := range stack {

     

       1338
       1338
       +
       		blob, err := comatproto.RepoUploadBlob(r.Context(), client, strings.NewReader(p.LatestPatch()))

     

       1339
       1339
       +
       		if err != nil {

     

       1340
       1340
       +
       			log.Println("failed to upload patch blob", err)

     

       1341
       1341
       +
       			s.pages.Notice(w, "pull", "Failed to create pull request. Try again later.")

     

       1342
       1342
       +
       			return

     

       1343
       1343
       +
       		}

     

       1344
       1344
       +
       

     

       1331
       1345
        
       		record := p.AsRecord()

     

       1332
       1332
       -
       		write := comatproto.RepoApplyWrites_Input_Writes_Elem{

     

       1346
       1346
       +
       		record.PatchBlob = blob.Blob

     

       1347
       1347
       +
       		writes = append(writes, &comatproto.RepoApplyWrites_Input_Writes_Elem{

     

       1333
       1348
        
       			RepoApplyWrites_Create: &comatproto.RepoApplyWrites_Create{

     

       1334
       1349
        
       				Collection: tangled.RepoPullNSID,

     

       1335
       1350
        
       				Rkey:       &p.Rkey,

     
···

       1337
       1352
        
       					Val: &record,

     

       1338
       1353
        
       				},

     

       1339
       1354
        
       			},

     

       1340
       1340
       -
       		}

     

       1341
       1341
       -
       		writes = append(writes, &write)

     

       1355
       1355
       +
       		})

     

       1342
       1356
        
       	}

     

       1343
       1357
        
       	_, err = comatproto.RepoApplyWrites(r.Context(), client, &comatproto.RepoApplyWrites_Input{

     

       1344
       1358
        
       		Repo:   user.Did,

     
···

       1366
       1380
        
       			s.pages.Notice(w, "pull", "Failed to create pull request. Try again later.")

     

       1367
       1381
        
       			return

     

       1368
       1382
        
       		}

     

       1383
       1383
       +
       

     

       1369
       1384
        
       	}

     

       1370
       1385
        
       

     

       1371
       1386
        
       	if err = tx.Commit(); err != nil {

     

       1372
       1387
        
       		log.Println("failed to create pull request", err)

     

       1373
       1388
        
       		s.pages.Notice(w, "pull", "Failed to create pull request. Try again later.")

     

       1374
       1389
        
       		return

     

       1390
       1390
       +
       	}

     

       1391
       1391
       +
       

     

       1392
       1392
       +
       	// notify about each pull

     

       1393
       1393
       +
       	//

     

       1394
       1394
       +
       	// this is performed after tx.Commit, because it could result in a locked DB otherwise

     

       1395
       1395
       +
       	for _, p := range stack {

     

       1396
       1396
       +
       		s.notifier.NewPull(r.Context(), p)

     

       1375
       1397
        
       	}

     

       1376
       1398
        
       

     

       1377
       1399
        
       	ownerSlashRepo := reporesolver.GetBaseRepoPath(r, repo)

     
···

       1863
       1885
        
       		return

     

       1864
       1886
        
       	}

     

       1865
       1887
        
       

     

       1866
       1866
       -
       	var recordPullSource *tangled.RepoPull_Source

     

       1867
       1867
       -
       	if pull.IsBranchBased() {

     

       1868
       1868
       -
       		recordPullSource = &tangled.RepoPull_Source{

     

       1869
       1869
       -
       			Branch: pull.PullSource.Branch,

     

       1870
       1870
       -
       			Sha:    sourceRev,

     

       1871
       1871
       -
       		}

     

       1888
       1888
       +
       	blob, err := comatproto.RepoUploadBlob(r.Context(), client, strings.NewReader(patch))

     

       1889
       1889
       +
       	if err != nil {

     

       1890
       1890
       +
       		log.Println("failed to upload patch blob", err)

     

       1891
       1891
       +
       		s.pages.Notice(w, "resubmit-error", "Failed to update pull request on the PDS. Try again later.")

     

       1892
       1892
       +
       		return

     

       1872
       1893
        
       	}

     

       1873
       1873
       -
       	if pull.IsForkBased() {

     

       1874
       1874
       -
       		repoAt := pull.PullSource.RepoAt.String()

     

       1875
       1875
       -
       		recordPullSource = &tangled.RepoPull_Source{

     

       1876
       1876
       -
       			Branch: pull.PullSource.Branch,

     

       1877
       1877
       -
       			Repo:   &repoAt,

     

       1878
       1878
       -
       			Sha:    sourceRev,

     

       1879
       1879
       -
       		}

     

       1880
       1880
       -
       	}

     

       1894
       1894
       +
       	record := pull.AsRecord()

     

       1895
       1895
       +
       	record.PatchBlob = blob.Blob

     

       1896
       1896
       +
       	record.CreatedAt = time.Now().Format(time.RFC3339)

     

       1881
       1897
        
       

     

       1882
       1898
        
       	_, err = comatproto.RepoPutRecord(r.Context(), client, &comatproto.RepoPutRecord_Input{

     

       1883
       1899
        
       		Collection: tangled.RepoPullNSID,

     
···

       1885
       1901
        
       		Rkey:       pull.Rkey,

     

       1886
       1902
        
       		SwapRecord: ex.Cid,

     

       1887
       1903
        
       		Record: &lexutil.LexiconTypeDecoder{

     

       1888
       1888
       -
       			Val: &tangled.RepoPull{

     

       1889
       1889
       -
       				Title: pull.Title,

     

       1890
       1890
       -
       				Target: &tangled.RepoPull_Target{

     

       1891
       1891
       -
       					Repo:   string(repo.RepoAt()),

     

       1892
       1892
       -
       					Branch: pull.TargetBranch,

     

       1893
       1893
       -
       				},

     

       1894
       1894
       -
       				Patch:     patch, // new patch

     

       1895
       1895
       -
       				Source:    recordPullSource,

     

       1896
       1896
       -
       				CreatedAt: time.Now().Format(time.RFC3339),

     

       1897
       1897
       -
       			},

     

       1904
       1904
       +
       			Val: &record,

     

       1898
       1905
        
       		},

     

       1899
       1906
        
       	})

     

       1900
       1907
        
       	if err != nil {

     
···

       1980
       1987
        
       	}

     

       1981
       1988
        
       	defer tx.Rollback()

     

       1982
       1989
        
       

     

       1990
       1990
       +
       	client, err := s.oauth.AuthorizedClient(r)

     

       1991
       1991
       +
       	if err != nil {

     

       1992
       1992
       +
       		log.Println("failed to authorize client")

     

       1993
       1993
       +
       		s.pages.Notice(w, "resubmit-error", "Failed to create pull request. Try again later.")

     

       1994
       1994
       +
       		return

     

       1995
       1995
       +
       	}

     

       1996
       1996
       +
       

     

       1983
       1997
        
       	// pds updates to make

     

       1984
       1998
        
       	var writes []*comatproto.RepoApplyWrites_Input_Writes_Elem

     

       1985
       1999
        
       

     
···

       2013
       2027
        
       			return

     

       2014
       2028
        
       		}

     

       2015
       2029
        
       

     

       2030
       2030
       +
       		blob, err := comatproto.RepoUploadBlob(r.Context(), client, strings.NewReader(patch))

     

       2031
       2031
       +
       		if err != nil {

     

       2032
       2032
       +
       			log.Println("failed to upload patch blob", err)

     

       2033
       2033
       +
       			s.pages.Notice(w, "resubmit-error", "Failed to update pull request on the PDS. Try again later.")

     

       2034
       2034
       +
       			return

     

       2035
       2035
       +
       		}

     

       2016
       2036
        
       		record := p.AsRecord()

     

       2037
       2037
       +
       		record.PatchBlob = blob.Blob

     

       2017
       2038
        
       		writes = append(writes, &comatproto.RepoApplyWrites_Input_Writes_Elem{

     

       2018
       2039
        
       			RepoApplyWrites_Create: &comatproto.RepoApplyWrites_Create{

     

       2019
       2040
        
       				Collection: tangled.RepoPullNSID,

     
···

       2048
       2069
        
       			return

     

       2049
       2070
        
       		}

     

       2050
       2071
        
       

     

       2072
       2072
       +
       		blob, err := comatproto.RepoUploadBlob(r.Context(), client, strings.NewReader(patch))

     

       2073
       2073
       +
       		if err != nil {

     

       2074
       2074
       +
       			log.Println("failed to upload patch blob", err)

     

       2075
       2075
       +
       			s.pages.Notice(w, "resubmit-error", "Failed to update pull request on the PDS. Try again later.")

     

       2076
       2076
       +
       			return

     

       2077
       2077
       +
       		}

     

       2051
       2078
        
       		record := np.AsRecord()

     

       2052
       2052
       -
       

     

       2079
       2079
       +
       		record.PatchBlob = blob.Blob

     

       2053
       2080
        
       		writes = append(writes, &comatproto.RepoApplyWrites_Input_Writes_Elem{

     

       2054
       2081
        
       			RepoApplyWrites_Update: &comatproto.RepoApplyWrites_Update{

     

       2055
       2082
        
       				Collection: tangled.RepoPullNSID,

     
···

       2083
       2110
        
       	if err != nil {

     

       2084
       2111
        
       		log.Println("failed to resubmit pull", err)

     

       2085
       2112
        
       		s.pages.Notice(w, "pull-resubmit-error", "Failed to resubmit pull request. Try again later.")

     

       2086
       2086
       -
       		return

     

       2087
       2087
       -
       	}

     

       2088
       2088
       -
       

     

       2089
       2089
       -
       	client, err := s.oauth.AuthorizedClient(r)

     

       2090
       2090
       -
       	if err != nil {

     

       2091
       2091
       -
       		log.Println("failed to authorize client")

     

       2092
       2092
       -
       		s.pages.Notice(w, "resubmit-error", "Failed to create pull request. Try again later.")

     

       2093
       2113
        
       		return

     

       2094
       2114
        
       	}

     

       2095
       2115

+17

appview/state/git_http.go

···

       25
       25
        
       

     

       26
       26
        
       }

     

       27
       27
        
       

     

       28
       28
       +
       func (s *State) UploadArchive(w http.ResponseWriter, r *http.Request) {

     

       29
       29
       +
       	user, ok := r.Context().Value("resolvedId").(identity.Identity)

     

       30
       30
       +
       	if !ok {

     

       31
       31
       +
       		http.Error(w, "failed to resolve user", http.StatusInternalServerError)

     

       32
       32
       +
       		return

     

       33
       33
       +
       	}

     

       34
       34
       +
       	repo := r.Context().Value("repo").(*models.Repo)

     

       35
       35
       +
       

     

       36
       36
       +
       	scheme := "https"

     

       37
       37
       +
       	if s.config.Core.Dev {

     

       38
       38
       +
       		scheme = "http"

     

       39
       39
       +
       	}

     

       40
       40
       +
       

     

       41
       41
       +
       	targetURL := fmt.Sprintf("%s://%s/%s/%s/git-upload-archive?%s", scheme, repo.Knot, user.DID, repo.Name, r.URL.RawQuery)

     

       42
       42
       +
       	s.proxyRequest(w, r, targetURL)

     

       43
       43
       +
       }

     

       44
       44
       +
       

     

       28
       45
        
       func (s *State) UploadPack(w http.ResponseWriter, r *http.Request) {

     

       29
       46
        
       	user, ok := r.Context().Value("resolvedId").(identity.Identity)

     

       30
       47
        
       	if !ok {

appview/state/router.go

···

       101
       101
        
       

     

       102
       102
        
       			// These routes get proxied to the knot

     

       103
       103
        
       			r.Get("/info/refs", s.InfoRefs)

     

       104
       104
       +
       			r.Post("/git-upload-archive", s.UploadArchive)

     

       104
       105
        
       			r.Post("/git-upload-pack", s.UploadPack)

     

       105
       106
        
       			r.Post("/git-receive-pack", s.ReceivePack)

     

       106
       107

+1529

docs/DOCS.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: Tangled docs

     

       3
       3
       +
       author: The Tangled Contributors

     

       4
       4
       +
       date: 21 Sun, Dec 2025

     

       5
       5
       +
       ---

     

       6
       6
       +
       

     

       7
       7
       +
       # Introduction

     

       8
       8
       +
       

     

       9
       9
       +
       Tangled is a decentralized code hosting and collaboration

     

       10
       10
       +
       platform. Every component of Tangled is open-source and

     

       11
       11
       +
       self-hostable. [tangled.org](https://tangled.org) also

     

       12
       12
       +
       provides hosting and CI services that are free to use.

     

       13
       13
       +
       

     

       14
       14
       +
       There are several models for decentralized code

     

       15
       15
       +
       collaboration platforms, ranging from ActivityPub’s

     

       16
       16
       +
       (Forgejo) federated model, to Radicle’s entirely P2P model.

     

       17
       17
       +
       Our approach attempts to be the best of both worlds by

     

       18
       18
       +
       adopting the AT Protocol—a protocol for building decentralized

     

       19
       19
       +
       social applications with a central identity

     

       20
       20
       +
       

     

       21
       21
       +
       Our approach to this is the idea of “knots”. Knots are

     

       22
       22
       +
       lightweight, headless servers that enable users to host Git

     

       23
       23
       +
       repositories with ease. Knots are designed for either single

     

       24
       24
       +
       or multi-tenant use which is perfect for self-hosting on a

     

       25
       25
       +
       Raspberry Pi at home, or larger “community” servers. By

     

       26
       26
       +
       default, Tangled provides managed knots where you can host

     

       27
       27
       +
       your repositories for free.

     

       28
       28
       +
       

     

       29
       29
       +
       The appview at tangled.org acts as a consolidated "view"

     

       30
       30
       +
       into the whole network, allowing users to access, clone and

     

       31
       31
       +
       contribute to repositories hosted across different knots

     

       32
       32
       +
       seamlessly.

     

       33
       33
       +
       

     

       34
       34
       +
       # Quick start guide

     

       35
       35
       +
       

     

       36
       36
       +
       ## Login or sign up

     

       37
       37
       +
       

     

       38
       38
       +
       You can [login](https://tangled.org) by using your AT Protocol

     

       39
       39
       +
       account. If you are unclear on what that means, simply head

     

       40
       40
       +
       to the [signup](https://tangled.org/signup) page and create

     

       41
       41
       +
       an account. By doing so, you will be choosing Tangled as

     

       42
       42
       +
       your account provider (you will be granted a handle of the

     

       43
       43
       +
       form `user.tngl.sh`).

     

       44
       44
       +
       

     

       45
       45
       +
       In the AT Protocol network, users are free to choose their account

     

       46
       46
       +
       provider (known as a "Personal Data Service", or PDS), and

     

       47
       47
       +
       login to applications that support AT accounts.

     

       48
       48
       +
       

     

       49
       49
       +
       You can think of it as "one account for all of the atmosphere"!

     

       50
       50
       +
       

     

       51
       51
       +
       If you already have an AT account (you may have one if you

     

       52
       52
       +
       signed up to Bluesky, for example), you can login with the

     

       53
       53
       +
       same handle on Tangled (so just use `user.bsky.social` on

     

       54
       54
       +
       the login page).

     

       55
       55
       +
       

     

       56
       56
       +
       ## Add an SSH key

     

       57
       57
       +
       

     

       58
       58
       +
       Once you are logged in, you can start creating repositories

     

       59
       59
       +
       and pushing code. Tangled supports pushing git repositories

     

       60
       60
       +
       over SSH.

     

       61
       61
       +
       

     

       62
       62
       +
       First, you'll need to generate an SSH key if you don't

     

       63
       63
       +
       already have one:

     

       64
       64
       +
       

     

       65
       65
       +
       ```bash

     

       66
       66
       +
       ssh-keygen -t ed25519 -C "foo@bar.com"

     

       67
       67
       +
       ```

     

       68
       68
       +
       

     

       69
       69
       +
       When prompted, save the key to the default location

     

       70
       70
       +
       (`~/.ssh/id_ed25519`) and optionally set a passphrase.

     

       71
       71
       +
       

     

       72
       72
       +
       Copy your public key to your clipboard:

     

       73
       73
       +
       

     

       74
       74
       +
       ```bash

     

       75
       75
       +
       # on X11

     

       76
       76
       +
       cat ~/.ssh/id_ed25519.pub | xclip -sel c

     

       77
       77
       +
       

     

       78
       78
       +
       # on wayland

     

       79
       79
       +
       cat ~/.ssh/id_ed25519.pub | wl-copy

     

       80
       80
       +
       

     

       81
       81
       +
       # on macos

     

       82
       82
       +
       cat ~/.ssh/id_ed25519.pub | pbcopy

     

       83
       83
       +
       ```

     

       84
       84
       +
       

     

       85
       85
       +
       Now, navigate to 'Settings' -> 'Keys' and hit 'Add Key',

     

       86
       86
       +
       paste your public key, give it a descriptive name, and hit

     

       87
       87
       +
       save.

     

       88
       88
       +
       

     

       89
       89
       +
       ## Create a repository

     

       90
       90
       +
       

     

       91
       91
       +
       Once your SSH key is added, create your first repository:

     

       92
       92
       +
       

     

       93
       93
       +
       1. Hit the green `+` icon on the topbar, and select

     

       94
       94
       +
          repository

     

       95
       95
       +
       2. Enter a repository name

     

       96
       96
       +
       3. Add a description

     

       97
       97
       +
       4. Choose a knotserver to host this repository on

     

       98
       98
       +
       5. Hit create

     

       99
       99
       +
       

     

       100
       100
       +
       Knots are self-hostable, lightweight Git servers that can

     

       101
       101
       +
       host your repository. Unlike traditional code forges, your

     

       102
       102
       +
       code can live on any server. Read the [Knots](TODO) section

     

       103
       103
       +
       for more.

     

       104
       104
       +
       

     

       105
       105
       +
       ## Configure SSH

     

       106
       106
       +
       

     

       107
       107
       +
       To ensure Git uses the correct SSH key and connects smoothly

     

       108
       108
       +
       to Tangled, add this configuration to your `~/.ssh/config`

     

       109
       109
       +
       file:

     

       110
       110
       +
       

     

       111
       111
       +
       ```

     

       112
       112
       +
       Host tangled.org

     

       113
       113
       +
           Hostname tangled.org

     

       114
       114
       +
           User git

     

       115
       115
       +
           IdentityFile ~/.ssh/id_ed25519

     

       116
       116
       +
           AddressFamily inet

     

       117
       117
       +
       ```

     

       118
       118
       +
       

     

       119
       119
       +
       This tells SSH to use your specific key when connecting to

     

       120
       120
       +
       Tangled and prevents authentication issues if you have

     

       121
       121
       +
       multiple SSH keys.

     

       122
       122
       +
       

     

       123
       123
       +
       Note that this configuration only works for knotservers that

     

       124
       124
       +
       are hosted by tangled.org. If you use a custom knot, refer

     

       125
       125
       +
       to the [Knots](TODO) section.

     

       126
       126
       +
       

     

       127
       127
       +
       ## Push your first repository

     

       128
       128
       +
       

     

       129
       129
       +
       Initialize a new Git repository:

     

       130
       130
       +
       

     

       131
       131
       +
       ```bash

     

       132
       132
       +
       mkdir my-project

     

       133
       133
       +
       cd my-project

     

       134
       134
       +
       

     

       135
       135
       +
       git init

     

       136
       136
       +
       echo "# My Project" > README.md 

     

       137
       137
       +
       ```

     

       138
       138
       +
       

     

       139
       139
       +
       Add some content and push!

     

       140
       140
       +
       

     

       141
       141
       +
       ```bash

     

       142
       142
       +
       git add README.md

     

       143
       143
       +
       git commit -m "Initial commit"

     

       144
       144
       +
       git remote add origin git@tangled.org:user.tngl.sh/my-project

     

       145
       145
       +
       git push -u origin main

     

       146
       146
       +
       ```

     

       147
       147
       +
       

     

       148
       148
       +
       That's it! Your code is now hosted on Tangled.

     

       149
       149
       +
       

     

       150
       150
       +
       ## Migrating an existing repository

     

       151
       151
       +
       

     

       152
       152
       +
       Moving your repositories from GitHub, GitLab, Bitbucket, or

     

       153
       153
       +
       any other Git forge to Tangled is straightforward. You'll

     

       154
       154
       +
       simply change your repository's remote URL. At the moment,

     

       155
       155
       +
       Tangled does not have any tooling to migrate data such as

     

       156
       156
       +
       GitHub issues or pull requests.

     

       157
       157
       +
       

     

       158
       158
       +
       First, create a new repository on tangled.org as described

     

       159
       159
       +
       in the [Quick Start Guide](#create-a-repository).

     

       160
       160
       +
       

     

       161
       161
       +
       Navigate to your existing local repository:

     

       162
       162
       +
       

     

       163
       163
       +
       ```bash

     

       164
       164
       +
       cd /path/to/your/existing/repo

     

       165
       165
       +
       ```

     

       166
       166
       +
       

     

       167
       167
       +
       You can inspect your existing Git remote like so:

     

       168
       168
       +
       

     

       169
       169
       +
       ```bash

     

       170
       170
       +
       git remote -v

     

       171
       171
       +
       ```

     

       172
       172
       +
       

     

       173
       173
       +
       You'll see something like:

     

       174
       174
       +
       

     

       175
       175
       +
       ```

     

       176
       176
       +
       origin  git@github.com:username/my-project (fetch)

     

       177
       177
       +
       origin  git@github.com:username/my-project (push)

     

       178
       178
       +
       ```

     

       179
       179
       +
       

     

       180
       180
       +
       Update the remote URL to point to tangled:

     

       181
       181
       +
       

     

       182
       182
       +
       ```bash

     

       183
       183
       +
       git remote set-url origin git@tangled.org:user.tngl.sh/my-project

     

       184
       184
       +
       ```

     

       185
       185
       +
       

     

       186
       186
       +
       Verify the change:

     

       187
       187
       +
       

     

       188
       188
       +
       ```bash

     

       189
       189
       +
       git remote -v

     

       190
       190
       +
       ```

     

       191
       191
       +
       

     

       192
       192
       +
       You should now see:

     

       193
       193
       +
       

     

       194
       194
       +
       ```

     

       195
       195
       +
       origin  git@tangled.org:user.tngl.sh/my-project (fetch)

     

       196
       196
       +
       origin  git@tangled.org:user.tngl.sh/my-project (push)

     

       197
       197
       +
       ```

     

       198
       198
       +
       

     

       199
       199
       +
       Push all your branches and tags to Tangled:

     

       200
       200
       +
       

     

       201
       201
       +
       ```bash

     

       202
       202
       +
       git push -u origin --all

     

       203
       203
       +
       git push -u origin --tags

     

       204
       204
       +
       ```

     

       205
       205
       +
       

     

       206
       206
       +
       Your repository is now migrated to Tangled! All commit

     

       207
       207
       +
       history, branches, and tags have been preserved.

     

       208
       208
       +
       

     

       209
       209
       +
       ## Mirroring a repository to Tangled

     

       210
       210
       +
       

     

       211
       211
       +
       If you want to maintain your repository on multiple forges

     

       212
       212
       +
       simultaneously, for example, keeping your primary repository

     

       213
       213
       +
       on GitHub while mirroring to Tangled for backup or

     

       214
       214
       +
       redundancy, you can do so by adding multiple remotes.

     

       215
       215
       +
       

     

       216
       216
       +
       You can configure your local repository to push to both

     

       217
       217
       +
       Tangled and, say, GitHub. You may already have the following

     

       218
       218
       +
       setup:

     

       219
       219
       +
       

     

       220
       220
       +
       ```

     

       221
       221
       +
       $ git remote -v

     

       222
       222
       +
       origin  git@github.com:username/my-project (fetch)

     

       223
       223
       +
       origin  git@github.com:username/my-project (push)

     

       224
       224
       +
       ```

     

       225
       225
       +
       

     

       226
       226
       +
       Now add Tangled as an additional push URL to the same

     

       227
       227
       +
       remote:

     

       228
       228
       +
       

     

       229
       229
       +
       ```bash

     

       230
       230
       +
       git remote set-url --add --push origin git@tangled.org:user.tngl.sh/my-project

     

       231
       231
       +
       ```

     

       232
       232
       +
       

     

       233
       233
       +
       You also need to re-add the original URL as a push

     

       234
       234
       +
       destination (Git replaces the push URL when you use `--add`

     

       235
       235
       +
       the first time):

     

       236
       236
       +
       

     

       237
       237
       +
       ```bash

     

       238
       238
       +
       git remote set-url --add --push origin git@github.com:username/my-project

     

       239
       239
       +
       ```

     

       240
       240
       +
       

     

       241
       241
       +
       Verify your configuration:

     

       242
       242
       +
       

     

       243
       243
       +
       ```

     

       244
       244
       +
       $ git remote -v

     

       245
       245
       +
       origin  git@github.com:username/repo (fetch)

     

       246
       246
       +
       origin  git@tangled.org:username/my-project (push)

     

       247
       247
       +
       origin  git@github.com:username/repo (push)

     

       248
       248
       +
       ```

     

       249
       249
       +
       

     

       250
       250
       +
       Notice that there's one fetch URL (the primary remote) and

     

       251
       251
       +
       two push URLs. Now, whenever you push, Git will

     

       252
       252
       +
       automatically push to both remotes:

     

       253
       253
       +
       

     

       254
       254
       +
       ```bash

     

       255
       255
       +
       git push origin main

     

       256
       256
       +
       ```

     

       257
       257
       +
       

     

       258
       258
       +
       This single command pushes your `main` branch to both GitHub

     

       259
       259
       +
       and Tangled simultaneously.

     

       260
       260
       +
       

     

       261
       261
       +
       To push all branches and tags:

     

       262
       262
       +
       

     

       263
       263
       +
       ```bash

     

       264
       264
       +
       git push origin --all

     

       265
       265
       +
       git push origin --tags

     

       266
       266
       +
       ```

     

       267
       267
       +
       

     

       268
       268
       +
       If you prefer more control over which remote you push to,

     

       269
       269
       +
       you can maintain separate remotes:

     

       270
       270
       +
       

     

       271
       271
       +
       ```bash

     

       272
       272
       +
       git remote add github git@github.com:username/my-project

     

       273
       273
       +
       git remote add tangled git@tangled.org:username/my-project

     

       274
       274
       +
       ```

     

       275
       275
       +
       

     

       276
       276
       +
       Then push to each explicitly:

     

       277
       277
       +
       

     

       278
       278
       +
       ```bash

     

       279
       279
       +
       git push github main

     

       280
       280
       +
       git push tangled main

     

       281
       281
       +
       ```

     

       282
       282
       +
       

     

       283
       283
       +
       # Knot self-hosting guide

     

       284
       284
       +
       

     

       285
       285
       +
       So you want to run your own knot server? Great! Here are a few prerequisites:

     

       286
       286
       +
       

     

       287
       287
       +
       1. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux distribution of some kind.

     

       288
       288
       +
       2. A (sub)domain name. People generally use `knot.example.com`.

     

       289
       289
       +
       3. A valid SSL certificate for your domain.

     

       290
       290
       +
       

     

       291
       291
       +
       ## NixOS

     

       292
       292
       +
       

     

       293
       293
       +
       Refer to the [knot

     

       294
       294
       +
       module](https://tangled.org/tangled.org/core/blob/master/nix/modules/knot.nix)

     

       295
       295
       +
       for a full list of options. Sample configurations:

     

       296
       296
       +
       

     

       297
       297
       +
       - [The test VM](https://tangled.org/tangled.org/core/blob/master/nix/vm.nix#L85)

     

       298
       298
       +
       - [@pyrox.dev/nix](https://tangled.org/pyrox.dev/nix/blob/d19571cc1b5fe01035e1e6951ec8cf8a476b4dee/hosts/marvin/services/tangled.nix#L15-25)

     

       299
       299
       +
       

     

       300
       300
       +
       ## Docker

     

       301
       301
       +
       

     

       302
       302
       +
       Refer to

     

       303
       303
       +
       [@tangled.org/knot-docker](https://tangled.org/@tangled.org/knot-docker).

     

       304
       304
       +
       Note that this is community maintained.

     

       305
       305
       +
       

     

       306
       306
       +
       ## Manual setup

     

       307
       307
       +
       

     

       308
       308
       +
       First, clone this repository:

     

       309
       309
       +
       

     

       310
       310
       +
       ```

     

       311
       311
       +
       git clone https://tangled.org/@tangled.org/core

     

       312
       312
       +
       ```

     

       313
       313
       +
       

     

       314
       314
       +
       Then, build the `knot` CLI. This is the knot administration

     

       315
       315
       +
       and operation tool. For the purpose of this guide, we're

     

       316
       316
       +
       only concerned with these subcommands:

     

       317
       317
       +
       

     

       318
       318
       +
        * `knot server`: the main knot server process, typically

     

       319
       319
       +
          run as a supervised service

     

       320
       320
       +
        * `knot guard`: handles role-based access control for git

     

       321
       321
       +
          over SSH (you'll never have to run this yourself)

     

       322
       322
       +
        * `knot keys`: fetches SSH keys associated with your knot;

     

       323
       323
       +
          we'll use this to generate the SSH

     

       324
       324
       +
          `AuthorizedKeysCommand`

     

       325
       325
       +
       

     

       326
       326
       +
       ```

     

       327
       327
       +
       cd core

     

       328
       328
       +
       export CGO_ENABLED=1

     

       329
       329
       +
       go build -o knot ./cmd/knot

     

       330
       330
       +
       ```

     

       331
       331
       +
       

     

       332
       332
       +
       Next, move the `knot` binary to a location owned by `root` --

     

       333
       333
       +
       `/usr/local/bin/` is a good choice. Make sure the binary itself is also owned by `root`:

     

       334
       334
       +
       

     

       335
       335
       +
       ```

     

       336
       336
       +
       sudo mv knot /usr/local/bin/knot

     

       337
       337
       +
       sudo chown root:root /usr/local/bin/knot

     

       338
       338
       +
       ```

     

       339
       339
       +
       

     

       340
       340
       +
       This is necessary because SSH `AuthorizedKeysCommand` requires [really

     

       341
       341
       +
       specific permissions](https://stackoverflow.com/a/27638306). The

     

       342
       342
       +
       `AuthorizedKeysCommand` specifies a command that is run by `sshd` to

     

       343
       343
       +
       retrieve a user's public SSH keys dynamically for authentication. Let's

     

       344
       344
       +
       set that up.

     

       345
       345
       +
       

     

       346
       346
       +
       ```

     

       347
       347
       +
       sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF

     

       348
       348
       +
       Match User git

     

       349
       349
       +
         AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys

     

       350
       350
       +
         AuthorizedKeysCommandUser nobody

     

       351
       351
       +
       EOF

     

       352
       352
       +
       ```

     

       353
       353
       +
       

     

       354
       354
       +
       Then, reload `sshd`:

     

       355
       355
       +
       

     

       356
       356
       +
       ```

     

       357
       357
       +
       sudo systemctl reload ssh

     

       358
       358
       +
       ```

     

       359
       359
       +
       

     

       360
       360
       +
       Next, create the `git` user. We'll use the `git` user's home directory

     

       361
       361
       +
       to store repositories:

     

       362
       362
       +
       

     

       363
       363
       +
       ```

     

       364
       364
       +
       sudo adduser git

     

       365
       365
       +
       ```

     

       366
       366
       +
       

     

       367
       367
       +
       Create `/home/git/.knot.env` with the following, updating the values as

     

       368
       368
       +
       necessary. The `KNOT_SERVER_OWNER` should be set to your

     

       369
       369
       +
       DID, you can find your DID in the [Settings](https://tangled.sh/settings) page.

     

       370
       370
       +
       

     

       371
       371
       +
       ```

     

       372
       372
       +
       KNOT_REPO_SCAN_PATH=/home/git

     

       373
       373
       +
       KNOT_SERVER_HOSTNAME=knot.example.com

     

       374
       374
       +
       APPVIEW_ENDPOINT=https://tangled.org

     

       375
       375
       +
       KNOT_SERVER_OWNER=did:plc:foobar

     

       376
       376
       +
       KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444

     

       377
       377
       +
       KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555

     

       378
       378
       +
       ```

     

       379
       379
       +
       

     

       380
       380
       +
       If you run a Linux distribution that uses systemd, you can use the provided

     

       381
       381
       +
       service file to run the server. Copy

     

       382
       382
       +
       [`knotserver.service`](/systemd/knotserver.service)

     

       383
       383
       +
       to `/etc/systemd/system/`. Then, run:

     

       384
       384
       +
       

     

       385
       385
       +
       ```

     

       386
       386
       +
       systemctl enable knotserver

     

       387
       387
       +
       systemctl start knotserver

     

       388
       388
       +
       ```

     

       389
       389
       +
       

     

       390
       390
       +
       The last step is to configure a reverse proxy like Nginx or Caddy to front your

     

       391
       391
       +
       knot. Here's an example configuration for Nginx:

     

       392
       392
       +
       

     

       393
       393
       +
       ```

     

       394
       394
       +
       server {

     

       395
       395
       +
           listen 80;

     

       396
       396
       +
           listen [::]:80;

     

       397
       397
       +
           server_name knot.example.com;

     

       398
       398
       +
       

     

       399
       399
       +
           location / {

     

       400
       400
       +
               proxy_pass http://localhost:5555;

     

       401
       401
       +
               proxy_set_header Host $host;

     

       402
       402
       +
               proxy_set_header X-Real-IP $remote_addr;

     

       403
       403
       +
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

     

       404
       404
       +
               proxy_set_header X-Forwarded-Proto $scheme;

     

       405
       405
       +
           }

     

       406
       406
       +
       

     

       407
       407
       +
           # wss endpoint for git events

     

       408
       408
       +
           location /events {

     

       409
       409
       +
               proxy_set_header   X-Forwarded-For $remote_addr;

     

       410
       410
       +
               proxy_set_header   Host $http_host;

     

       411
       411
       +
               proxy_set_header Upgrade websocket;

     

       412
       412
       +
               proxy_set_header Connection Upgrade;

     

       413
       413
       +
               proxy_pass http://localhost:5555;

     

       414
       414
       +
           }

     

       415
       415
       +
         # additional config for SSL/TLS go here.

     

       416
       416
       +
       }

     

       417
       417
       +
       

     

       418
       418
       +
       ```

     

       419
       419
       +
       

     

       420
       420
       +
       Remember to use Let's Encrypt or similar to procure a certificate for your

     

       421
       421
       +
       knot domain.

     

       422
       422
       +
       

     

       423
       423
       +
       You should now have a running knot server! You can finalize

     

       424
       424
       +
       your registration by hitting the `verify` button on the

     

       425
       425
       +
       [/settings/knots](https://tangled.org/settings/knots) page. This simply creates

     

       426
       426
       +
       a record on your PDS to announce the existence of the knot.

     

       427
       427
       +
       

     

       428
       428
       +
       ### Custom paths

     

       429
       429
       +
       

     

       430
       430
       +
       (This section applies to manual setup only. Docker users should edit the mounts

     

       431
       431
       +
       in `docker-compose.yml` instead.)

     

       432
       432
       +
       

     

       433
       433
       +
       Right now, the database and repositories of your knot lives in `/home/git`. You

     

       434
       434
       +
       can move these paths if you'd like to store them in another folder. Be careful

     

       435
       435
       +
       when adjusting these paths:

     

       436
       436
       +
       

     

       437
       437
       +
       * Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent

     

       438
       438
       +
       any possible side effects. Remember to restart it once you're done.

     

       439
       439
       +
       * Make backups before moving in case something goes wrong.

     

       440
       440
       +
       * Make sure the `git` user can read and write from the new paths.

     

       441
       441
       +
       

     

       442
       442
       +
       #### Database

     

       443
       443
       +
       

     

       444
       444
       +
       As an example, let's say the current database is at `/home/git/knotserver.db`,

     

       445
       445
       +
       and we want to move it to `/home/git/database/knotserver.db`.

     

       446
       446
       +
       

     

       447
       447
       +
       Copy the current database to the new location. Make sure to copy the `.db-shm`

     

       448
       448
       +
       and `.db-wal` files if they exist.

     

       449
       449
       +
       

     

       450
       450
       +
       ```

     

       451
       451
       +
       mkdir /home/git/database

     

       452
       452
       +
       cp /home/git/knotserver.db* /home/git/database

     

       453
       453
       +
       ```

     

       454
       454
       +
       

     

       455
       455
       +
       In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to

     

       456
       456
       +
       the new file path (_not_ the directory):

     

       457
       457
       +
       

     

       458
       458
       +
       ```

     

       459
       459
       +
       KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db

     

       460
       460
       +
       ```

     

       461
       461
       +
       

     

       462
       462
       +
       #### Repositories

     

       463
       463
       +
       

     

       464
       464
       +
       As an example, let's say the repositories are currently in `/home/git`, and we

     

       465
       465
       +
       want to move them into `/home/git/repositories`.

     

       466
       466
       +
       

     

       467
       467
       +
       Create the new folder, then move the existing repositories (if there are any):

     

       468
       468
       +
       

     

       469
       469
       +
       ```

     

       470
       470
       +
       mkdir /home/git/repositories

     

       471
       471
       +
       # move all DIDs into the new folder; these will vary for you!

     

       472
       472
       +
       mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories

     

       473
       473
       +
       ```

     

       474
       474
       +
       

     

       475
       475
       +
       In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH`

     

       476
       476
       +
       to the new directory:

     

       477
       477
       +
       

     

       478
       478
       +
       ```

     

       479
       479
       +
       KNOT_REPO_SCAN_PATH=/home/git/repositories

     

       480
       480
       +
       ```

     

       481
       481
       +
       

     

       482
       482
       +
       Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated

     

       483
       483
       +
       repository path:

     

       484
       484
       +
       

     

       485
       485
       +
       ```

     

       486
       486
       +
       sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF

     

       487
       487
       +
       Match User git

     

       488
       488
       +
         AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories

     

       489
       489
       +
         AuthorizedKeysCommandUser nobody

     

       490
       490
       +
       EOF

     

       491
       491
       +
       ```

     

       492
       492
       +
       

     

       493
       493
       +
       Make sure to restart your SSH server!

     

       494
       494
       +
       

     

       495
       495
       +
       #### MOTD (message of the day)

     

       496
       496
       +
       

     

       497
       497
       +
       To configure the MOTD used ("Welcome to this knot!" by default), edit the

     

       498
       498
       +
       `/home/git/motd` file:

     

       499
       499
       +
       

     

       500
       500
       +
       ```

     

       501
       501
       +
       printf "Hi from this knot!\n" > /home/git/motd

     

       502
       502
       +
       ```

     

       503
       503
       +
       

     

       504
       504
       +
       Note that you should add a newline at the end if setting a non-empty message

     

       505
       505
       +
       since the knot won't do this for you.

     

       506
       506
       +
       

     

       507
       507
       +
       # Spindles

     

       508
       508
       +
       

     

       509
       509
       +
       ## Pipelines

     

       510
       510
       +
       

     

       511
       511
       +
       Spindle workflows allow you to write CI/CD pipelines in a

     

       512
       512
       +
       simple format. They're located in the `.tangled/workflows`

     

       513
       513
       +
       directory at the root of your repository, and are defined

     

       514
       514
       +
       using YAML.

     

       515
       515
       +
       

     

       516
       516
       +
       The fields are:

     

       517
       517
       +
       

     

       518
       518
       +
       - [Trigger](#trigger): A **required** field that defines

     

       519
       519
       +
         when a workflow should be triggered.

     

       520
       520
       +
       - [Engine](#engine): A **required** field that defines which

     

       521
       521
       +
         engine a workflow should run on.

     

       522
       522
       +
       - [Clone options](#clone-options): An **optional** field

     

       523
       523
       +
         that defines how the repository should be cloned.

     

       524
       524
       +
       - [Dependencies](#dependencies): An **optional** field that

     

       525
       525
       +
         allows you to list dependencies you may need.

     

       526
       526
       +
       - [Environment](#environment): An **optional** field that

     

       527
       527
       +
         allows you to define environment variables.

     

       528
       528
       +
       - [Steps](#steps): An **optional** field that allows you to

     

       529
       529
       +
         define what steps should run in the workflow.

     

       530
       530
       +
       

     

       531
       531
       +
       ### Trigger

     

       532
       532
       +
       

     

       533
       533
       +
       The first thing to add to a workflow is the trigger, which

     

       534
       534
       +
       defines when a workflow runs. This is defined using a `when`

     

       535
       535
       +
       field, which takes in a list of conditions. Each condition

     

       536
       536
       +
       has the following fields:

     

       537
       537
       +
       

     

       538
       538
       +
       - `event`: This is a **required** field that defines when

     

       539
       539
       +
         your workflow should run. It's a list that can take one or

     

       540
       540
       +
         more of the following values:

     

       541
       541
       +
         - `push`: The workflow should run every time a commit is

     

       542
       542
       +
           pushed to the repository.

     

       543
       543
       +
         - `pull_request`: The workflow should run every time a

     

       544
       544
       +
           pull request is made or updated.

     

       545
       545
       +
         - `manual`: The workflow can be triggered manually.

     

       546
       546
       +
       - `branch`: Defines which branches the workflow should run

     

       547
       547
       +
         for. If used with the `push` event, commits to the

     

       548
       548
       +
         branch(es) listed here will trigger the workflow. If used

     

       549
       549
       +
         with the `pull_request` event, updates to pull requests

     

       550
       550
       +
         targeting the branch(es) listed here will trigger the

     

       551
       551
       +
         workflow. This field has no effect with the `manual`

     

       552
       552
       +
         event. Supports glob patterns using `*` and `**` (e.g.,

     

       553
       553
       +
         `main`, `develop`, `release-*`). Either `branch` or `tag`

     

       554
       554
       +
         (or both) must be specified for `push` events.

     

       555
       555
       +
       - `tag`: Defines which tags the workflow should run for.

     

       556
       556
       +
         Only used with the `push` event - when tags matching the

     

       557
       557
       +
         pattern(s) listed here are pushed, the workflow will

     

       558
       558
       +
         trigger. This field has no effect with `pull_request` or

     

       559
       559
       +
         `manual` events. Supports glob patterns using `*` and `**`

     

       560
       560
       +
         (e.g., `v*`, `v1.*`, `release-**`). Either `branch` or

     

       561
       561
       +
         `tag` (or both) must be specified for `push` events.

     

       562
       562
       +
       

     

       563
       563
       +
       For example, if you'd like to define a workflow that runs

     

       564
       564
       +
       when commits are pushed to the `main` and `develop`

     

       565
       565
       +
       branches, or when pull requests that target the `main`

     

       566
       566
       +
       branch are updated, or manually, you can do so with:

     

       567
       567
       +
       

     

       568
       568
       +
       ```yaml

     

       569
       569
       +
       when:

     

       570
       570
       +
         - event: ["push", "manual"]

     

       571
       571
       +
           branch: ["main", "develop"]

     

       572
       572
       +
         - event: ["pull_request"]

     

       573
       573
       +
           branch: ["main"]

     

       574
       574
       +
       ```

     

       575
       575
       +
       

     

       576
       576
       +
       You can also trigger workflows on tag pushes. For instance,

     

       577
       577
       +
       to run a deployment workflow when tags matching `v*` are

     

       578
       578
       +
       pushed:

     

       579
       579
       +
       

     

       580
       580
       +
       ```yaml

     

       581
       581
       +
       when:

     

       582
       582
       +
         - event: ["push"]

     

       583
       583
       +
           tag: ["v*"]

     

       584
       584
       +
       ```

     

       585
       585
       +
       

     

       586
       586
       +
       You can even combine branch and tag patterns in a single

     

       587
       587
       +
       constraint (the workflow triggers if either matches):

     

       588
       588
       +
       

     

       589
       589
       +
       ```yaml

     

       590
       590
       +
       when:

     

       591
       591
       +
         - event: ["push"]

     

       592
       592
       +
           branch: ["main", "release-*"]

     

       593
       593
       +
           tag: ["v*", "stable"]

     

       594
       594
       +
       ```

     

       595
       595
       +
       

     

       596
       596
       +
       ### Engine

     

       597
       597
       +
       

     

       598
       598
       +
       Next is the engine on which the workflow should run, defined

     

       599
       599
       +
       using the **required** `engine` field. The currently

     

       600
       600
       +
       supported engines are:

     

       601
       601
       +
       

     

       602
       602
       +
       - `nixery`: This uses an instance of

     

       603
       603
       +
         [Nixery](https://nixery.dev) to run steps, which allows

     

       604
       604
       +
         you to add [dependencies](#dependencies) from

     

       605
       605
       +
         Nixpkgs (https://github.com/NixOS/nixpkgs). You can

     

       606
       606
       +
         search for packages on https://search.nixos.org, and

     

       607
       607
       +
         there's a pretty good chance the package(s) you're looking

     

       608
       608
       +
         for will be there.

     

       609
       609
       +
       

     

       610
       610
       +
       Example:

     

       611
       611
       +
       

     

       612
       612
       +
       ```yaml

     

       613
       613
       +
       engine: "nixery"

     

       614
       614
       +
       ```

     

       615
       615
       +
       

     

       616
       616
       +
       ### Clone options

     

       617
       617
       +
       

     

       618
       618
       +
       When a workflow starts, the first step is to clone the

     

       619
       619
       +
       repository. You can customize this behavior using the

     

       620
       620
       +
       **optional** `clone` field. It has the following fields:

     

       621
       621
       +
       

     

       622
       622
       +
       - `skip`: Setting this to `true` will skip cloning the

     

       623
       623
       +
         repository. This can be useful if your workflow is doing

     

       624
       624
       +
         something that doesn't require anything from the

     

       625
       625
       +
         repository itself. This is `false` by default.

     

       626
       626
       +
       - `depth`: This sets the number of commits, or the "clone

     

       627
       627
       +
         depth", to fetch from the repository. For example, if you

     

       628
       628
       +
         set this to 2, the last 2 commits will be fetched. By

     

       629
       629
       +
         default, the depth is set to 1, meaning only the most

     

       630
       630
       +
         recent commit will be fetched, which is the commit that

     

       631
       631
       +
         triggered the workflow.

     

       632
       632
       +
       - `submodules`: If you use Git submodules

     

       633
       633
       +
         (https://git-scm.com/book/en/v2/Git-Tools-Submodules)

     

       634
       634
       +
         in your repository, setting this field to `true` will

     

       635
       635
       +
         recursively fetch all submodules. This is `false` by

     

       636
       636
       +
         default.

     

       637
       637
       +
       

     

       638
       638
       +
       The default settings are:

     

       639
       639
       +
       

     

       640
       640
       +
       ```yaml

     

       641
       641
       +
       clone:

     

       642
       642
       +
         skip: false

     

       643
       643
       +
         depth: 1

     

       644
       644
       +
         submodules: false

     

       645
       645
       +
       ```

     

       646
       646
       +
       

     

       647
       647
       +
       ### Dependencies

     

       648
       648
       +
       

     

       649
       649
       +
       Usually when you're running a workflow, you'll need

     

       650
       650
       +
       additional dependencies. The `dependencies` field lets you

     

       651
       651
       +
       define which dependencies to get, and from where. It's a

     

       652
       652
       +
       key-value map, with the key being the registry to fetch

     

       653
       653
       +
       dependencies from, and the value being the list of

     

       654
       654
       +
       dependencies to fetch.

     

       655
       655
       +
       

     

       656
       656
       +
       Say you want to fetch Node.js and Go from `nixpkgs`, and a

     

       657
       657
       +
       package called `my_pkg` you've made from your own registry

     

       658
       658
       +
       at your repository at

     

       659
       659
       +
       `https://tangled.org/@example.com/my_pkg`. You can define

     

       660
       660
       +
       those dependencies like so:

     

       661
       661
       +
       

     

       662
       662
       +
       ```yaml

     

       663
       663
       +
       dependencies:

     

       664
       664
       +
         # nixpkgs

     

       665
       665
       +
         nixpkgs:

     

       666
       666
       +
           - nodejs

     

       667
       667
       +
           - go

     

       668
       668
       +
         # custom registry

     

       669
       669
       +
         git+https://tangled.org/@example.com/my_pkg:

     

       670
       670
       +
           - my_pkg

     

       671
       671
       +
       ```

     

       672
       672
       +
       

     

       673
       673
       +
       Now these dependencies are available to use in your

     

       674
       674
       +
       workflow!

     

       675
       675
       +
       

     

       676
       676
       +
       ### Environment

     

       677
       677
       +
       

     

       678
       678
       +
       The `environment` field allows you define environment

     

       679
       679
       +
       variables that will be available throughout the entire

     

       680
       680
       +
       workflow. **Do not put secrets here, these environment

     

       681
       681
       +
       variables are visible to anyone viewing the repository. You

     

       682
       682
       +
       can add secrets for pipelines in your repository's

     

       683
       683
       +
       settings.**

     

       684
       684
       +
       

     

       685
       685
       +
       Example:

     

       686
       686
       +
       

     

       687
       687
       +
       ```yaml

     

       688
       688
       +
       environment:

     

       689
       689
       +
         GOOS: "linux"

     

       690
       690
       +
         GOARCH: "arm64"

     

       691
       691
       +
         NODE_ENV: "production"

     

       692
       692
       +
         MY_ENV_VAR: "MY_ENV_VALUE"

     

       693
       693
       +
       ```

     

       694
       694
       +
       

     

       695
       695
       +
       ### Steps

     

       696
       696
       +
       

     

       697
       697
       +
       The `steps` field allows you to define what steps should run

     

       698
       698
       +
       in the workflow. It's a list of step objects, each with the

     

       699
       699
       +
       following fields:

     

       700
       700
       +
       

     

       701
       701
       +
       - `name`: This field allows you to give your step a name.

     

       702
       702
       +
         This name is visible in your workflow runs, and is used to

     

       703
       703
       +
         describe what the step is doing.

     

       704
       704
       +
       - `command`: This field allows you to define a command to

     

       705
       705
       +
         run in that step. The step is run in a Bash shell, and the

     

       706
       706
       +
         logs from the command will be visible in the pipelines

     

       707
       707
       +
         page on the Tangled website. The

     

       708
       708
       +
         [dependencies](#dependencies) you added will be available

     

       709
       709
       +
         to use here.

     

       710
       710
       +
       - `environment`: Similar to the global

     

       711
       711
       +
         [environment](#environment) config, this **optional**

     

       712
       712
       +
         field is a key-value map that allows you to set

     

       713
       713
       +
         environment variables for the step. **Do not put secrets

     

       714
       714
       +
         here, these environment variables are visible to anyone

     

       715
       715
       +
         viewing the repository. You can add secrets for pipelines

     

       716
       716
       +
         in your repository's settings.**

     

       717
       717
       +
       

     

       718
       718
       +
       Example:

     

       719
       719
       +
       

     

       720
       720
       +
       ```yaml

     

       721
       721
       +
       steps:

     

       722
       722
       +
         - name: "Build backend"

     

       723
       723
       +
           command: "go build"

     

       724
       724
       +
           environment:

     

       725
       725
       +
             GOOS: "darwin"

     

       726
       726
       +
             GOARCH: "arm64"

     

       727
       727
       +
         - name: "Build frontend"

     

       728
       728
       +
           command: "npm run build"

     

       729
       729
       +
           environment:

     

       730
       730
       +
             NODE_ENV: "production"

     

       731
       731
       +
       ```

     

       732
       732
       +
       

     

       733
       733
       +
       ### Complete workflow

     

       734
       734
       +
       

     

       735
       735
       +
       ```yaml

     

       736
       736
       +
       # .tangled/workflows/build.yml

     

       737
       737
       +
       

     

       738
       738
       +
       when:

     

       739
       739
       +
         - event: ["push", "manual"]

     

       740
       740
       +
           branch: ["main", "develop"]

     

       741
       741
       +
         - event: ["pull_request"]

     

       742
       742
       +
           branch: ["main"]

     

       743
       743
       +
       

     

       744
       744
       +
       engine: "nixery"

     

       745
       745
       +
       

     

       746
       746
       +
       # using the default values

     

       747
       747
       +
       clone:

     

       748
       748
       +
         skip: false

     

       749
       749
       +
         depth: 1

     

       750
       750
       +
         submodules: false

     

       751
       751
       +
       

     

       752
       752
       +
       dependencies:

     

       753
       753
       +
         # nixpkgs

     

       754
       754
       +
         nixpkgs:

     

       755
       755
       +
           - nodejs

     

       756
       756
       +
           - go

     

       757
       757
       +
         # custom registry

     

       758
       758
       +
         git+https://tangled.org/@example.com/my_pkg:

     

       759
       759
       +
           - my_pkg

     

       760
       760
       +
       

     

       761
       761
       +
       environment:

     

       762
       762
       +
         GOOS: "linux"

     

       763
       763
       +
         GOARCH: "arm64"

     

       764
       764
       +
         NODE_ENV: "production"

     

       765
       765
       +
         MY_ENV_VAR: "MY_ENV_VALUE"

     

       766
       766
       +
       

     

       767
       767
       +
       steps:

     

       768
       768
       +
         - name: "Build backend"

     

       769
       769
       +
           command: "go build"

     

       770
       770
       +
           environment:

     

       771
       771
       +
             GOOS: "darwin"

     

       772
       772
       +
             GOARCH: "arm64"

     

       773
       773
       +
         - name: "Build frontend"

     

       774
       774
       +
           command: "npm run build"

     

       775
       775
       +
           environment:

     

       776
       776
       +
             NODE_ENV: "production"

     

       777
       777
       +
       ```

     

       778
       778
       +
       

     

       779
       779
       +
       If you want another example of a workflow, you can look at

     

       780
       780
       +
       the one [Tangled uses to build the

     

       781
       781
       +
       project](https://tangled.org/@tangled.org/core/blob/master/.tangled/workflows/build.yml).

     

       782
       782
       +
       

     

       783
       783
       +
       ## Self-hosting guide

     

       784
       784
       +
       

     

       785
       785
       +
       ### Prerequisites

     

       786
       786
       +
       

     

       787
       787
       +
       * Go

     

       788
       788
       +
       * Docker (the only supported backend currently)

     

       789
       789
       +
       

     

       790
       790
       +
       ### Configuration

     

       791
       791
       +
       

     

       792
       792
       +
       Spindle is configured using environment variables. The following environment variables are available:

     

       793
       793
       +
       

     

       794
       794
       +
       * `SPINDLE_SERVER_LISTEN_ADDR`: The address the server listens on (default: `"0.0.0.0:6555"`).

     

       795
       795
       +
       * `SPINDLE_SERVER_DB_PATH`: The path to the SQLite database file (default: `"spindle.db"`).

     

       796
       796
       +
       * `SPINDLE_SERVER_HOSTNAME`: The hostname of the server (required).

     

       797
       797
       +
       * `SPINDLE_SERVER_JETSTREAM_ENDPOINT`: The endpoint of the Jetstream server (default: `"wss://jetstream1.us-west.bsky.network/subscribe"`).

     

       798
       798
       +
       * `SPINDLE_SERVER_DEV`: A boolean indicating whether the server is running in development mode (default: `false`).

     

       799
       799
       +
       * `SPINDLE_SERVER_OWNER`: The DID of the owner (required).

     

       800
       800
       +
       * `SPINDLE_PIPELINES_NIXERY`: The Nixery URL (default: `"nixery.tangled.sh"`).

     

       801
       801
       +
       * `SPINDLE_PIPELINES_WORKFLOW_TIMEOUT`: The default workflow timeout (default: `"5m"`).

     

       802
       802
       +
       * `SPINDLE_PIPELINES_LOG_DIR`: The directory to store workflow logs (default: `"/var/log/spindle"`).

     

       803
       803
       +
       

     

       804
       804
       +
       ### Running spindle

     

       805
       805
       +
       

     

       806
       806
       +
       1.  **Set the environment variables.**  For example:

     

       807
       807
       +
       

     

       808
       808
       +
           ```shell

     

       809
       809
       +
           export SPINDLE_SERVER_HOSTNAME="your-hostname"

     

       810
       810
       +
           export SPINDLE_SERVER_OWNER="your-did"

     

       811
       811
       +
           ```

     

       812
       812
       +
       

     

       813
       813
       +
       2.  **Build the Spindle binary.**

     

       814
       814
       +
       

     

       815
       815
       +
           ```shell

     

       816
       816
       +
           cd core

     

       817
       817
       +
           go mod download

     

       818
       818
       +
           go build -o cmd/spindle/spindle cmd/spindle/main.go

     

       819
       819
       +
           ```

     

       820
       820
       +
       

     

       821
       821
       +
       3.  **Create the log directory.**

     

       822
       822
       +
       

     

       823
       823
       +
           ```shell

     

       824
       824
       +
           sudo mkdir -p /var/log/spindle

     

       825
       825
       +
           sudo chown $USER:$USER -R /var/log/spindle

     

       826
       826
       +
           ```

     

       827
       827
       +
       

     

       828
       828
       +
       4.  **Run the Spindle binary.**

     

       829
       829
       +
       

     

       830
       830
       +
           ```shell

     

       831
       831
       +
           ./cmd/spindle/spindle

     

       832
       832
       +
           ```

     

       833
       833
       +
       

     

       834
       834
       +
       Spindle will now start, connect to the Jetstream server, and begin processing pipelines.

     

       835
       835
       +
       

     

       836
       836
       +
       ## Architecture

     

       837
       837
       +
       

     

       838
       838
       +
       Spindle is a small CI runner service. Here's a high-level overview of how it operates:

     

       839
       839
       +
       

     

       840
       840
       +
       * Listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and

     

       841
       841
       +
       [`sh.tangled.repo`](/lexicons/repo.json) records on the Jetstream.

     

       842
       842
       +
       * When a new repo record comes through (typically when you add a spindle to a

     

       843
       843
       +
       repo from the settings), spindle then resolves the underlying knot and

     

       844
       844
       +
       subscribes to repo events (see:

     

       845
       845
       +
       [`sh.tangled.pipeline`](/lexicons/pipeline.json)).

     

       846
       846
       +
       * The spindle engine then handles execution of the pipeline, with results and

     

       847
       847
       +
       logs beamed on the spindle event stream over WebSocket

     

       848
       848
       +
       

     

       849
       849
       +
       ### The engine

     

       850
       850
       +
       

     

       851
       851
       +
       At present, the only supported backend is Docker (and Podman, if Docker

     

       852
       852
       +
       compatibility is enabled, so that `/run/docker.sock` is created). spindle

     

       853
       853
       +
       executes each step in the pipeline in a fresh container, with state persisted

     

       854
       854
       +
       across steps within the `/tangled/workspace` directory.

     

       855
       855
       +
       

     

       856
       856
       +
       The base image for the container is constructed on the fly using

     

       857
       857
       +
       [Nixery](https://nixery.dev), which is handy for caching layers for frequently

     

       858
       858
       +
       used packages.

     

       859
       859
       +
       

     

       860
       860
       +
       The pipeline manifest is [specified here](https://docs.tangled.org/spindles.html#pipelines).

     

       861
       861
       +
       

     

       862
       862
       +
       ## Secrets with openbao

     

       863
       863
       +
       

     

       864
       864
       +
       This document covers setting up spindle to use OpenBao for secrets

     

       865
       865
       +
       management via OpenBao Proxy instead of the default SQLite backend.

     

       866
       866
       +
       

     

       867
       867
       +
       ### Overview

     

       868
       868
       +
       

     

       869
       869
       +
       Spindle now uses OpenBao Proxy for secrets management. The proxy handles

     

       870
       870
       +
       authentication automatically using AppRole credentials, while spindle

     

       871
       871
       +
       connects to the local proxy instead of directly to the OpenBao server.

     

       872
       872
       +
       

     

       873
       873
       +
       This approach provides better security, automatic token renewal, and

     

       874
       874
       +
       simplified application code.

     

       875
       875
       +
       

     

       876
       876
       +
       ### Installation

     

       877
       877
       +
       

     

       878
       878
       +
       Install OpenBao from Nixpkgs:

     

       879
       879
       +
       

     

       880
       880
       +
       ```bash

     

       881
       881
       +
       nix shell nixpkgs#openbao   # for a local server

     

       882
       882
       +
       ```

     

       883
       883
       +
       

     

       884
       884
       +
       ### Setup

     

       885
       885
       +
       

     

       886
       886
       +
       The setup process can is documented for both local development and production.

     

       887
       887
       +
       

     

       888
       888
       +
       #### Local development

     

       889
       889
       +
       

     

       890
       890
       +
       Start OpenBao in dev mode:

     

       891
       891
       +
       

     

       892
       892
       +
       ```bash

     

       893
       893
       +
       bao server -dev -dev-root-token-id="root" -dev-listen-address=127.0.0.1:8201

     

       894
       894
       +
       ```

     

       895
       895
       +
       

     

       896
       896
       +
       This starts OpenBao on `http://localhost:8201` with a root token.

     

       897
       897
       +
       

     

       898
       898
       +
       Set up environment for bao CLI:

     

       899
       899
       +
       

     

       900
       900
       +
       ```bash

     

       901
       901
       +
       export BAO_ADDR=http://localhost:8200

     

       902
       902
       +
       export BAO_TOKEN=root

     

       903
       903
       +
       ```

     

       904
       904
       +
       

     

       905
       905
       +
       #### Production

     

       906
       906
       +
       

     

       907
       907
       +
       You would typically use a systemd service with a

     

       908
       908
       +
       configuration file. Refer to

     

       909
       909
       +
       [@tangled.org/infra](https://tangled.org/@tangled.org/infra)

     

       910
       910
       +
       for how this can be achieved using Nix.

     

       911
       911
       +
       

     

       912
       912
       +
       Then, initialize the bao server:

     

       913
       913
       +
       

     

       914
       914
       +
       ```bash

     

       915
       915
       +
       bao operator init -key-shares=1 -key-threshold=1

     

       916
       916
       +
       ```

     

       917
       917
       +
       

     

       918
       918
       +
       This will print out an unseal key and a root key. Save them

     

       919
       919
       +
       somewhere (like a password manager). Then unseal the vault

     

       920
       920
       +
       to begin setting it up:

     

       921
       921
       +
       

     

       922
       922
       +
       ```bash

     

       923
       923
       +
       bao operator unseal <unseal_key>

     

       924
       924
       +
       ```

     

       925
       925
       +
       

     

       926
       926
       +
       All steps below remain the same across both dev and

     

       927
       927
       +
       production setups.

     

       928
       928
       +
       

     

       929
       929
       +
       #### Configure openbao server

     

       930
       930
       +
       

     

       931
       931
       +
       Create the spindle KV mount:

     

       932
       932
       +
       

     

       933
       933
       +
       ```bash

     

       934
       934
       +
       bao secrets enable -path=spindle -version=2 kv

     

       935
       935
       +
       ```

     

       936
       936
       +
       

     

       937
       937
       +
       Set up AppRole authentication and policy:

     

       938
       938
       +
       

     

       939
       939
       +
       Create a policy file `spindle-policy.hcl`:

     

       940
       940
       +
       

     

       941
       941
       +
       ```hcl

     

       942
       942
       +
       # Full access to spindle KV v2 data

     

       943
       943
       +
       path "spindle/data/*" {

     

       944
       944
       +
         capabilities = ["create", "read", "update", "delete"]

     

       945
       945
       +
       }

     

       946
       946
       +
       

     

       947
       947
       +
       # Access to metadata for listing and management

     

       948
       948
       +
       path "spindle/metadata/*" {

     

       949
       949
       +
         capabilities = ["list", "read", "delete", "update"]

     

       950
       950
       +
       }

     

       951
       951
       +
       

     

       952
       952
       +
       # Allow listing at root level

     

       953
       953
       +
       path "spindle/" {

     

       954
       954
       +
         capabilities = ["list"]

     

       955
       955
       +
       }

     

       956
       956
       +
       

     

       957
       957
       +
       # Required for connection testing and health checks

     

       958
       958
       +
       path "auth/token/lookup-self" {

     

       959
       959
       +
         capabilities = ["read"]

     

       960
       960
       +
       }

     

       961
       961
       +
       ```

     

       962
       962
       +
       

     

       963
       963
       +
       Apply the policy and create an AppRole:

     

       964
       964
       +
       

     

       965
       965
       +
       ```bash

     

       966
       966
       +
       bao policy write spindle-policy spindle-policy.hcl

     

       967
       967
       +
       bao auth enable approle

     

       968
       968
       +
       bao write auth/approle/role/spindle \

     

       969
       969
       +
           token_policies="spindle-policy" \

     

       970
       970
       +
           token_ttl=1h \

     

       971
       971
       +
           token_max_ttl=4h \

     

       972
       972
       +
           bind_secret_id=true \

     

       973
       973
       +
           secret_id_ttl=0 \

     

       974
       974
       +
           secret_id_num_uses=0

     

       975
       975
       +
       ```

     

       976
       976
       +
       

     

       977
       977
       +
       Get the credentials:

     

       978
       978
       +
       

     

       979
       979
       +
       ```bash

     

       980
       980
       +
       # Get role ID (static)

     

       981
       981
       +
       ROLE_ID=$(bao read -field=role_id auth/approle/role/spindle/role-id)

     

       982
       982
       +
       

     

       983
       983
       +
       # Generate secret ID

     

       984
       984
       +
       SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/spindle/secret-id)

     

       985
       985
       +
       

     

       986
       986
       +
       echo "Role ID: $ROLE_ID"

     

       987
       987
       +
       echo "Secret ID: $SECRET_ID"

     

       988
       988
       +
       ```

     

       989
       989
       +
       

     

       990
       990
       +
       #### Create proxy configuration

     

       991
       991
       +
       

     

       992
       992
       +
       Create the credential files:

     

       993
       993
       +
       

     

       994
       994
       +
       ```bash

     

       995
       995
       +
       # Create directory for OpenBao files

     

       996
       996
       +
       mkdir -p /tmp/openbao

     

       997
       997
       +
       

     

       998
       998
       +
       # Save credentials

     

       999
       999
       +
       echo "$ROLE_ID" > /tmp/openbao/role-id

     

       1000
       1000
       +
       echo "$SECRET_ID" > /tmp/openbao/secret-id

     

       1001
       1001
       +
       chmod 600 /tmp/openbao/role-id /tmp/openbao/secret-id

     

       1002
       1002
       +
       ```

     

       1003
       1003
       +
       

     

       1004
       1004
       +
       Create a proxy configuration file `/tmp/openbao/proxy.hcl`:

     

       1005
       1005
       +
       

     

       1006
       1006
       +
       ```hcl

     

       1007
       1007
       +
       # OpenBao server connection

     

       1008
       1008
       +
       vault {

     

       1009
       1009
       +
         address = "http://localhost:8200"

     

       1010
       1010
       +
       }

     

       1011
       1011
       +
       

     

       1012
       1012
       +
       # Auto-Auth using AppRole

     

       1013
       1013
       +
       auto_auth {

     

       1014
       1014
       +
         method "approle" {

     

       1015
       1015
       +
           mount_path = "auth/approle"

     

       1016
       1016
       +
           config = {

     

       1017
       1017
       +
             role_id_file_path   = "/tmp/openbao/role-id"

     

       1018
       1018
       +
             secret_id_file_path = "/tmp/openbao/secret-id"

     

       1019
       1019
       +
           }

     

       1020
       1020
       +
         }

     

       1021
       1021
       +
       

     

       1022
       1022
       +
         # Optional: write token to file for debugging

     

       1023
       1023
       +
         sink "file" {

     

       1024
       1024
       +
           config = {

     

       1025
       1025
       +
             path = "/tmp/openbao/token"

     

       1026
       1026
       +
             mode = 0640

     

       1027
       1027
       +
           }

     

       1028
       1028
       +
         }

     

       1029
       1029
       +
       }

     

       1030
       1030
       +
       

     

       1031
       1031
       +
       # Proxy listener for spindle

     

       1032
       1032
       +
       listener "tcp" {

     

       1033
       1033
       +
         address     = "127.0.0.1:8201"

     

       1034
       1034
       +
         tls_disable = true

     

       1035
       1035
       +
       }

     

       1036
       1036
       +
       

     

       1037
       1037
       +
       # Enable API proxy with auto-auth token

     

       1038
       1038
       +
       api_proxy {

     

       1039
       1039
       +
         use_auto_auth_token = true

     

       1040
       1040
       +
       }

     

       1041
       1041
       +
       

     

       1042
       1042
       +
       # Enable response caching

     

       1043
       1043
       +
       cache {

     

       1044
       1044
       +
         use_auto_auth_token = true

     

       1045
       1045
       +
       }

     

       1046
       1046
       +
       

     

       1047
       1047
       +
       # Logging

     

       1048
       1048
       +
       log_level = "info"

     

       1049
       1049
       +
       ```

     

       1050
       1050
       +
       

     

       1051
       1051
       +
       #### Start the proxy

     

       1052
       1052
       +
       

     

       1053
       1053
       +
       Start OpenBao Proxy:

     

       1054
       1054
       +
       

     

       1055
       1055
       +
       ```bash

     

       1056
       1056
       +
       bao proxy -config=/tmp/openbao/proxy.hcl

     

       1057
       1057
       +
       ```

     

       1058
       1058
       +
       

     

       1059
       1059
       +
       The proxy will authenticate with OpenBao and start listening on

     

       1060
       1060
       +
       `127.0.0.1:8201`.

     

       1061
       1061
       +
       

     

       1062
       1062
       +
       #### Configure spindle

     

       1063
       1063
       +
       

     

       1064
       1064
       +
       Set these environment variables for spindle:

     

       1065
       1065
       +
       

     

       1066
       1066
       +
       ```bash

     

       1067
       1067
       +
       export SPINDLE_SERVER_SECRETS_PROVIDER=openbao

     

       1068
       1068
       +
       export SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR=http://127.0.0.1:8201

     

       1069
       1069
       +
       export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle

     

       1070
       1070
       +
       ```

     

       1071
       1071
       +
       

     

       1072
       1072
       +
       On startup, spindle will now connect to the local proxy,

     

       1073
       1073
       +
       which handles all authentication automatically.

     

       1074
       1074
       +
       

     

       1075
       1075
       +
       ### Production setup for proxy

     

       1076
       1076
       +
       

     

       1077
       1077
       +
       For production, you'll want to run the proxy as a service:

     

       1078
       1078
       +
       

     

       1079
       1079
       +
       Place your production configuration in

     

       1080
       1080
       +
       `/etc/openbao/proxy.hcl` with proper TLS settings for the

     

       1081
       1081
       +
       vault connection.

     

       1082
       1082
       +
       

     

       1083
       1083
       +
       ### Verifying setup

     

       1084
       1084
       +
       

     

       1085
       1085
       +
       Test the proxy directly:

     

       1086
       1086
       +
       

     

       1087
       1087
       +
       ```bash

     

       1088
       1088
       +
       # Check proxy health

     

       1089
       1089
       +
       curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/sys/health

     

       1090
       1090
       +
       

     

       1091
       1091
       +
       # Test token lookup through proxy

     

       1092
       1092
       +
       curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/auth/token/lookup-self

     

       1093
       1093
       +
       ```

     

       1094
       1094
       +
       

     

       1095
       1095
       +
       Test OpenBao operations through the server:

     

       1096
       1096
       +
       

     

       1097
       1097
       +
       ```bash

     

       1098
       1098
       +
       # List all secrets

     

       1099
       1099
       +
       bao kv list spindle/

     

       1100
       1100
       +
       

     

       1101
       1101
       +
       # Add a test secret via the spindle API, then check it exists

     

       1102
       1102
       +
       bao kv list spindle/repos/

     

       1103
       1103
       +
       

     

       1104
       1104
       +
       # Get a specific secret

     

       1105
       1105
       +
       bao kv get spindle/repos/your_repo_path/SECRET_NAME

     

       1106
       1106
       +
       ```

     

       1107
       1107
       +
       

     

       1108
       1108
       +
       ### How it works

     

       1109
       1109
       +
       

     

       1110
       1110
       +
       - Spindle connects to OpenBao Proxy on localhost (typically

     

       1111
       1111
       +
         port 8200 or 8201)

     

       1112
       1112
       +
       - The proxy authenticates with OpenBao using AppRole

     

       1113
       1113
       +
         credentials

     

       1114
       1114
       +
       - All spindle requests go through the proxy, which injects

     

       1115
       1115
       +
         authentication tokens

     

       1116
       1116
       +
       - Secrets are stored at

     

       1117
       1117
       +
         `spindle/repos/{sanitized_repo_path}/{secret_key}`

     

       1118
       1118
       +
       - Repository paths like `did:plc:alice/myrepo` become

     

       1119
       1119
       +
         `did_plc_alice_myrepo`

     

       1120
       1120
       +
       - The proxy handles all token renewal automatically

     

       1121
       1121
       +
       - Spindle no longer manages tokens or authentication

     

       1122
       1122
       +
         directly

     

       1123
       1123
       +
       

     

       1124
       1124
       +
       ### Troubleshooting

     

       1125
       1125
       +
       

     

       1126
       1126
       +
       **Connection refused**: Check that the OpenBao Proxy is

     

       1127
       1127
       +
       running and listening on the configured address.

     

       1128
       1128
       +
       

     

       1129
       1129
       +
       **403 errors**: Verify the AppRole credentials are correct

     

       1130
       1130
       +
       and the policy has the necessary permissions.

     

       1131
       1131
       +
       

     

       1132
       1132
       +
       **404 route errors**: The spindle KV mount probably doesn't

     

       1133
       1133
       +
       exist—run the mount creation step again.

     

       1134
       1134
       +
       

     

       1135
       1135
       +
       **Proxy authentication failures**: Check the proxy logs and

     

       1136
       1136
       +
       verify the role-id and secret-id files are readable and

     

       1137
       1137
       +
       contain valid credentials.

     

       1138
       1138
       +
       

     

       1139
       1139
       +
       **Secret not found after writing**: This can indicate policy

     

       1140
       1140
       +
       permission issues. Verify the policy includes both

     

       1141
       1141
       +
       `spindle/data/*` and `spindle/metadata/*` paths with

     

       1142
       1142
       +
       appropriate capabilities.

     

       1143
       1143
       +
       

     

       1144
       1144
       +
       Check proxy logs:

     

       1145
       1145
       +
       

     

       1146
       1146
       +
       ```bash

     

       1147
       1147
       +
       # If running as systemd service

     

       1148
       1148
       +
       journalctl -u openbao-proxy -f

     

       1149
       1149
       +
       

     

       1150
       1150
       +
       # If running directly, check the console output

     

       1151
       1151
       +
       ```

     

       1152
       1152
       +
       

     

       1153
       1153
       +
       Test AppRole authentication manually:

     

       1154
       1154
       +
       

     

       1155
       1155
       +
       ```bash

     

       1156
       1156
       +
       bao write auth/approle/login \

     

       1157
       1157
       +
           role_id="$(cat /tmp/openbao/role-id)" \

     

       1158
       1158
       +
           secret_id="$(cat /tmp/openbao/secret-id)"

     

       1159
       1159
       +
       ```

     

       1160
       1160
       +
       

     

       1161
       1161
       +
       # Migrating knots and spindles

     

       1162
       1162
       +
       

     

       1163
       1163
       +
       Sometimes, non-backwards compatible changes are made to the

     

       1164
       1164
       +
       knot/spindle XRPC APIs. If you host a knot or a spindle, you

     

       1165
       1165
       +
       will need to follow this guide to upgrade. Typically, this

     

       1166
       1166
       +
       only requires you to deploy the newest version.

     

       1167
       1167
       +
       

     

       1168
       1168
       +
       This document is laid out in reverse-chronological order.

     

       1169
       1169
       +
       Newer migration guides are listed first, and older guides

     

       1170
       1170
       +
       are further down the page.

     

       1171
       1171
       +
       

     

       1172
       1172
       +
       ## Upgrading from v1.8.x

     

       1173
       1173
       +
       

     

       1174
       1174
       +
       After v1.8.2, the HTTP API for knots and spindles has been

     

       1175
       1175
       +
       deprecated and replaced with XRPC. Repositories on outdated

     

       1176
       1176
       +
       knots will not be viewable from the appview. Upgrading is

     

       1177
       1177
       +
       straightforward however.

     

       1178
       1178
       +
       

     

       1179
       1179
       +
       For knots:

     

       1180
       1180
       +
       

     

       1181
       1181
       +
       - Upgrade to the latest tag (v1.9.0 or above)

     

       1182
       1182
       +
       - Head to the [knot dashboard](https://tangled.org/settings/knots) and

     

       1183
       1183
       +
         hit the "retry" button to verify your knot

     

       1184
       1184
       +
       

     

       1185
       1185
       +
       For spindles:

     

       1186
       1186
       +
       

     

       1187
       1187
       +
       - Upgrade to the latest tag (v1.9.0 or above)

     

       1188
       1188
       +
       - Head to the [spindle

     

       1189
       1189
       +
         dashboard](https://tangled.org/settings/spindles) and hit the

     

       1190
       1190
       +
         "retry" button to verify your spindle

     

       1191
       1191
       +
       

     

       1192
       1192
       +
       ## Upgrading from v1.7.x

     

       1193
       1193
       +
       

     

       1194
       1194
       +
       After v1.7.0, knot secrets have been deprecated. You no

     

       1195
       1195
       +
       longer need a secret from the appview to run a knot. All

     

       1196
       1196
       +
       authorized commands to knots are managed via [Inter-Service

     

       1197
       1197
       +
       Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).

     

       1198
       1198
       +
       Knots will be read-only until upgraded.

     

       1199
       1199
       +
       

     

       1200
       1200
       +
       Upgrading is quite easy, in essence:

     

       1201
       1201
       +
       

     

       1202
       1202
       +
       - `KNOT_SERVER_SECRET` is no more, you can remove this

     

       1203
       1203
       +
         environment variable entirely

     

       1204
       1204
       +
       - `KNOT_SERVER_OWNER` is now required on boot, set this to

     

       1205
       1205
       +
         your DID. You can find your DID in the

     

       1206
       1206
       +
         [settings](https://tangled.org/settings) page.

     

       1207
       1207
       +
       - Restart your knot once you have replaced the environment

     

       1208
       1208
       +
         variable

     

       1209
       1209
       +
       - Head to the [knot dashboard](https://tangled.org/settings/knots) and

     

       1210
       1210
       +
         hit the "retry" button to verify your knot. This simply

     

       1211
       1211
       +
         writes a `sh.tangled.knot` record to your PDS.

     

       1212
       1212
       +
       

     

       1213
       1213
       +
       If you use the nix module, simply bump the flake to the

     

       1214
       1214
       +
       latest revision, and change your config block like so:

     

       1215
       1215
       +
       

     

       1216
       1216
       +
       ```diff

     

       1217
       1217
       +
        services.tangled.knot = {

     

       1218
       1218
       +
          enable = true;

     

       1219
       1219
       +
          server = {

     

       1220
       1220
       +
       -    secretFile = /path/to/secret;

     

       1221
       1221
       +
       +    owner = "did:plc:foo";

     

       1222
       1222
       +
          };

     

       1223
       1223
       +
        };

     

       1224
       1224
       +
       ```

     

       1225
       1225
       +
       

     

       1226
       1226
       +
       # Hacking on Tangled

     

       1227
       1227
       +
       

     

       1228
       1228
       +
       We highly recommend [installing

     

       1229
       1229
       +
       Nix](https://nixos.org/download/) (the package manager)

     

       1230
       1230
       +
       before working on the codebase. The Nix flake provides a lot

     

       1231
       1231
       +
       of helpers to get started and most importantly, builds and

     

       1232
       1232
       +
       dev shells are entirely deterministic.

     

       1233
       1233
       +
       

     

       1234
       1234
       +
       To set up your dev environment:

     

       1235
       1235
       +
       

     

       1236
       1236
       +
       ```bash

     

       1237
       1237
       +
       nix develop

     

       1238
       1238
       +
       ```

     

       1239
       1239
       +
       

     

       1240
       1240
       +
       Non-Nix users can look at the `devShell` attribute in the

     

       1241
       1241
       +
       `flake.nix` file to determine necessary dependencies.

     

       1242
       1242
       +
       

     

       1243
       1243
       +
       ## Running the appview

     

       1244
       1244
       +
       

     

       1245
       1245
       +
       The Nix flake also exposes a few `app` attributes (run `nix

     

       1246
       1246
       +
       flake show` to see a full list of what the flake provides),

     

       1247
       1247
       +
       one of the apps runs the appview with the `air`

     

       1248
       1248
       +
       live-reloader:

     

       1249
       1249
       +
       

     

       1250
       1250
       +
       ```bash

     

       1251
       1251
       +
       TANGLED_DEV=true nix run .#watch-appview

     

       1252
       1252
       +
       

     

       1253
       1253
       +
       # TANGLED_DB_PATH might be of interest to point to

     

       1254
       1254
       +
       # different sqlite DBs

     

       1255
       1255
       +
       

     

       1256
       1256
       +
       # in a separate shell, you can live-reload tailwind

     

       1257
       1257
       +
       nix run .#watch-tailwind

     

       1258
       1258
       +
       ```

     

       1259
       1259
       +
       

     

       1260
       1260
       +
       To authenticate with the appview, you will need Redis and

     

       1261
       1261
       +
       OAuth JWKs to be set up:

     

       1262
       1262
       +
       

     

       1263
       1263
       +
       ```

     

       1264
       1264
       +
       # OAuth JWKs should already be set up by the Nix devshell:

     

       1265
       1265
       +
       echo $TANGLED_OAUTH_CLIENT_SECRET

     

       1266
       1266
       +
       z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc

     

       1267
       1267
       +
       

     

       1268
       1268
       +
       echo $TANGLED_OAUTH_CLIENT_KID

     

       1269
       1269
       +
       1761667908

     

       1270
       1270
       +
       

     

       1271
       1271
       +
       # if not, you can set it up yourself:

     

       1272
       1272
       +
       goat key generate -t P-256

     

       1273
       1273
       +
       Key Type: P-256 / secp256r1 / ES256 private key

     

       1274
       1274
       +
       Secret Key (Multibase Syntax): save this securely (eg, add to password manager)

     

       1275
       1275
       +
               z42tuPDKRfM2mz2Kv953ARen2jmrPA8S9LX9tRq4RVcUMwwL

     

       1276
       1276
       +
       Public Key (DID Key Syntax): share or publish this (eg, in DID document)

     

       1277
       1277
       +
               did:key:zDnaeUBxtG6Xuv3ATJE4GaWeyXM3jyamJsZw3bSPpxx4bNXDR

     

       1278
       1278
       +
       

     

       1279
       1279
       +
       # the secret key from above

     

       1280
       1280
       +
       export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..."

     

       1281
       1281
       +
       

     

       1282
       1282
       +
       # Run Redis in a new shell to store OAuth sessions

     

       1283
       1283
       +
       redis-server

     

       1284
       1284
       +
       ```

     

       1285
       1285
       +
       

     

       1286
       1286
       +
       ## Running knots and spindles

     

       1287
       1287
       +
       

     

       1288
       1288
       +
       An end-to-end knot setup requires setting up a machine with

     

       1289
       1289
       +
       `sshd`, `AuthorizedKeysCommand`, and a Git user, which is

     

       1290
       1290
       +
       quite cumbersome. So the Nix flake provides a

     

       1291
       1291
       +
       `nixosConfiguration` to do so.

     

       1292
       1292
       +
       

     

       1293
       1293
       +
       <details>

     

       1294
       1294
       +
         <summary><strong>macOS users will have to set up a Nix Builder first</strong></summary>

     

       1295
       1295
       +
       

     

       1296
       1296
       +
         In order to build Tangled's dev VM on macOS, you will

     

       1297
       1297
       +
         first need to set up a Linux Nix builder. The recommended

     

       1298
       1298
       +
         way to do so is to run a [`darwin.linux-builder`

     

       1299
       1299
       +
         VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)

     

       1300
       1300
       +
         and to register it in `nix.conf` as a builder for Linux

     

       1301
       1301
       +
         with the same architecture as your Mac (`linux-aarch64` if

     

       1302
       1302
       +
         you are using Apple Silicon).

     

       1303
       1303
       +
       

     

       1304
       1304
       +
         > IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside

     

       1305
       1305
       +
         > the Tangled repo so that it doesn't conflict with the other VM. For example,

     

       1306
       1306
       +
         > you can do

     

       1307
       1307
       +
         >

     

       1308
       1308
       +
         > ```shell

     

       1309
       1309
       +
         > cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder

     

       1310
       1310
       +
         > ```

     

       1311
       1311
       +
         >

     

       1312
       1312
       +
         > to store the builder VM in a temporary dir.

     

       1313
       1313
       +
         >

     

       1314
       1314
       +
         > You should read and follow [all the other intructions][darwin builder vm] to

     

       1315
       1315
       +
         >  avoid subtle problems.

     

       1316
       1316
       +
       

     

       1317
       1317
       +
         Alternatively, you can use any other method to set up a

     

       1318
       1318
       +
         Linux machine with Nix installed that you can `sudo ssh`

     

       1319
       1319
       +
         into (in other words, root user on your Mac has to be able

     

       1320
       1320
       +
         to ssh into the Linux machine without entering a password)

     

       1321
       1321
       +
         and that has the same architecture as your Mac. See

     

       1322
       1322
       +
         [remote builder

     

       1323
       1323
       +
         instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)

     

       1324
       1324
       +
         for how to register such a builder in `nix.conf`.

     

       1325
       1325
       +
       

     

       1326
       1326
       +
         > WARNING: If you'd like to use

     

       1327
       1327
       +
         > [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or

     

       1328
       1328
       +
         > [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo

     

       1329
       1329
       +
         > ssh` works can be tricky. It seems to be [possible with

     

       1330
       1330
       +
         > Orbstack](https://github.com/orgs/orbstack/discussions/1669).

     

       1331
       1331
       +
       

     

       1332
       1332
       +
       </details>

     

       1333
       1333
       +
       

     

       1334
       1334
       +
       To begin, grab your DID from http://localhost:3000/settings.

     

       1335
       1335
       +
       Then, set `TANGLED_VM_KNOT_OWNER` and

     

       1336
       1336
       +
       `TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a

     

       1337
       1337
       +
       lightweight NixOS VM like so:

     

       1338
       1338
       +
       

     

       1339
       1339
       +
       ```bash

     

       1340
       1340
       +
       nix run --impure .#vm

     

       1341
       1341
       +
       

     

       1342
       1342
       +
       # type `poweroff` at the shell to exit the VM

     

       1343
       1343
       +
       ```

     

       1344
       1344
       +
       

     

       1345
       1345
       +
       This starts a knot on port 6444, a spindle on port 6555

     

       1346
       1346
       +
       with `ssh` exposed on port 2222.

     

       1347
       1347
       +
       

     

       1348
       1348
       +
       Once the services are running, head to

     

       1349
       1349
       +
       http://localhost:3000/settings/knots and hit "Verify". It should

     

       1350
       1350
       +
       verify the ownership of the services instantly if everything

     

       1351
       1351
       +
       went smoothly.

     

       1352
       1352
       +
       

     

       1353
       1353
       +
       You can push repositories to this VM with this ssh config

     

       1354
       1354
       +
       block on your main machine:

     

       1355
       1355
       +
       

     

       1356
       1356
       +
       ```bash

     

       1357
       1357
       +
       Host nixos-shell

     

       1358
       1358
       +
           Hostname localhost

     

       1359
       1359
       +
           Port 2222

     

       1360
       1360
       +
           User git

     

       1361
       1361
       +
           IdentityFile ~/.ssh/my_tangled_key

     

       1362
       1362
       +
       ```

     

       1363
       1363
       +
       

     

       1364
       1364
       +
       Set up a remote called `local-dev` on a git repo:

     

       1365
       1365
       +
       

     

       1366
       1366
       +
       ```bash

     

       1367
       1367
       +
       git remote add local-dev git@nixos-shell:user/repo

     

       1368
       1368
       +
       git push local-dev main

     

       1369
       1369
       +
       ```

     

       1370
       1370
       +
       

     

       1371
       1371
       +
       The above VM should already be running a spindle on

     

       1372
       1372
       +
       `localhost:6555`. Head to http://localhost:3000/settings/spindles and

     

       1373
       1373
       +
       hit "Verify". You can then configure each repository to use

     

       1374
       1374
       +
       this spindle and run CI jobs.

     

       1375
       1375
       +
       

     

       1376
       1376
       +
       Of interest when debugging spindles:

     

       1377
       1377
       +
       

     

       1378
       1378
       +
       ```

     

       1379
       1379
       +
       # Service logs from journald:

     

       1380
       1380
       +
       journalctl -xeu spindle

     

       1381
       1381
       +
       

     

       1382
       1382
       +
       # CI job logs from disk:

     

       1383
       1383
       +
       ls /var/log/spindle

     

       1384
       1384
       +
       

     

       1385
       1385
       +
       # Debugging spindle database:

     

       1386
       1386
       +
       sqlite3 /var/lib/spindle/spindle.db

     

       1387
       1387
       +
       

     

       1388
       1388
       +
       # litecli has a nicer REPL interface:

     

       1389
       1389
       +
       litecli /var/lib/spindle/spindle.db

     

       1390
       1390
       +
       ```

     

       1391
       1391
       +
       

     

       1392
       1392
       +
       If for any reason you wish to disable either one of the

     

       1393
       1393
       +
       services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set

     

       1394
       1394
       +
       `services.tangled.spindle.enable` (or

     

       1395
       1395
       +
       `services.tangled.knot.enable`) to `false`.

     

       1396
       1396
       +
       

     

       1397
       1397
       +
       # Contribution guide

     

       1398
       1398
       +
       

     

       1399
       1399
       +
       ## Commit guidelines

     

       1400
       1400
       +
       

     

       1401
       1401
       +
       We follow a commit style similar to the Go project. Please keep commits:

     

       1402
       1402
       +
       

     

       1403
       1403
       +
       * **atomic**: each commit should represent one logical change

     

       1404
       1404
       +
       * **descriptive**: the commit message should clearly describe what the

     

       1405
       1405
       +
       change does and why it's needed

     

       1406
       1406
       +
       

     

       1407
       1407
       +
       ### Message format

     

       1408
       1408
       +
       

     

       1409
       1409
       +
       ```

     

       1410
       1410
       +
       <service/top-level directory>/<affected package/directory>: <short summary of change>

     

       1411
       1411
       +
       

     

       1412
       1412
       +
       Optional longer description can go here, if necessary. Explain what the

     

       1413
       1413
       +
       change does and why, especially if not obvious. Reference relevant

     

       1414
       1414
       +
       issues or PRs when applicable. These can be links for now since we don't

     

       1415
       1415
       +
       auto-link issues/PRs yet.

     

       1416
       1416
       +
       ```

     

       1417
       1417
       +
       

     

       1418
       1418
       +
       Here are some examples:

     

       1419
       1419
       +
       

     

       1420
       1420
       +
       ```

     

       1421
       1421
       +
       appview/state: fix token expiry check in middleware

     

       1422
       1422
       +
       

     

       1423
       1423
       +
       The previous check did not account for clock drift, leading to premature

     

       1424
       1424
       +
       token invalidation.

     

       1425
       1425
       +
       ```

     

       1426
       1426
       +
       

     

       1427
       1427
       +
       ```

     

       1428
       1428
       +
       knotserver/git/service: improve error checking in upload-pack

     

       1429
       1429
       +
       ```

     

       1430
       1430
       +
       

     

       1431
       1431
       +
       

     

       1432
       1432
       +
       ### General notes

     

       1433
       1433
       +
       

     

       1434
       1434
       +
       - PRs get merged "as-is" (fast-forward)—like applying a patch-series

     

       1435
       1435
       +
       using `git am`. At present, there is no squashing—so please author

     

       1436
       1436
       +
       your commits as they would appear on `master`, following the above

     

       1437
       1437
       +
       guidelines.

     

       1438
       1438
       +
       - If there is a lot of nesting, for example "appview:

     

       1439
       1439
       +
       pages/templates/repo/fragments: ...", these can be truncated down to

     

       1440
       1440
       +
       just "appview: repo/fragments: ...". If the change affects a lot of

     

       1441
       1441
       +
       subdirectories, you may abbreviate to just the top-level names, e.g.

     

       1442
       1442
       +
       "appview: ..." or "knotserver: ...".

     

       1443
       1443
       +
       - Keep commits lowercased with no trailing period.

     

       1444
       1444
       +
       - Use the imperative mood in the summary line (e.g., "fix bug" not

     

       1445
       1445
       +
       "fixed bug" or "fixes bug").

     

       1446
       1446
       +
       - Try to keep the summary line under 72 characters, but we aren't too

     

       1447
       1447
       +
       fussed about this.

     

       1448
       1448
       +
       - Follow the same formatting for PR titles if filled manually.

     

       1449
       1449
       +
       - Don't include unrelated changes in the same commit.

     

       1450
       1450
       +
       - Avoid noisy commit messages like "wip" or "final fix"—rewrite history

     

       1451
       1451
       +
       before submitting if necessary.

     

       1452
       1452
       +
       

     

       1453
       1453
       +
       ## Code formatting

     

       1454
       1454
       +
       

     

       1455
       1455
       +
       We use a variety of tools to format our code, and multiplex them with

     

       1456
       1456
       +
       [`treefmt`](https://treefmt.com). All you need to do to format your changes

     

       1457
       1457
       +
       is run `nix run .#fmt` (or just `treefmt` if you're in the devshell).

     

       1458
       1458
       +
       

     

       1459
       1459
       +
       ## Proposals for bigger changes

     

       1460
       1460
       +
       

     

       1461
       1461
       +
       Small fixes like typos, minor bugs, or trivial refactors can be

     

       1462
       1462
       +
       submitted directly as PRs.

     

       1463
       1463
       +
       

     

       1464
       1464
       +
       For larger changes—especially those introducing new features, significant

     

       1465
       1465
       +
       refactoring, or altering system behavior—please open a proposal first. This

     

       1466
       1466
       +
       helps us evaluate the scope, design, and potential impact before implementation.

     

       1467
       1467
       +
       

     

       1468
       1468
       +
       Create a new issue titled:

     

       1469
       1469
       +
       

     

       1470
       1470
       +
       ```

     

       1471
       1471
       +
       proposal: <affected scope>: <summary of change>

     

       1472
       1472
       +
       ```

     

       1473
       1473
       +
       

     

       1474
       1474
       +
       In the description, explain:

     

       1475
       1475
       +
       

     

       1476
       1476
       +
       - What the change is

     

       1477
       1477
       +
       - Why it's needed

     

       1478
       1478
       +
       - How you plan to implement it (roughly)

     

       1479
       1479
       +
       - Any open questions or tradeoffs

     

       1480
       1480
       +
       

     

       1481
       1481
       +
       We'll use the issue thread to discuss and refine the idea before moving

     

       1482
       1482
       +
       forward.

     

       1483
       1483
       +
       

     

       1484
       1484
       +
       ## Developer Certificate of Origin (DCO)

     

       1485
       1485
       +
       

     

       1486
       1486
       +
       We require all contributors to certify that they have the right to

     

       1487
       1487
       +
       submit the code they're contributing. To do this, we follow the

     

       1488
       1488
       +
       [Developer Certificate of Origin

     

       1489
       1489
       +
       (DCO)](https://developercertificate.org/).

     

       1490
       1490
       +
       

     

       1491
       1491
       +
       By signing your commits, you're stating that the contribution is your

     

       1492
       1492
       +
       own work, or that you have the right to submit it under the project's

     

       1493
       1493
       +
       license. This helps us keep things clean and legally sound.

     

       1494
       1494
       +
       

     

       1495
       1495
       +
       To sign your commit, just add the `-s` flag when committing:

     

       1496
       1496
       +
       

     

       1497
       1497
       +
       ```sh

     

       1498
       1498
       +
       git commit -s -m "your commit message"

     

       1499
       1499
       +
       ```

     

       1500
       1500
       +
       

     

       1501
       1501
       +
       This appends a line like:

     

       1502
       1502
       +
       

     

       1503
       1503
       +
       ```

     

       1504
       1504
       +
       Signed-off-by: Your Name <your.email@example.com>

     

       1505
       1505
       +
       ```

     

       1506
       1506
       +
       

     

       1507
       1507
       +
       We won't merge commits if they aren't signed off. If you forget, you can

     

       1508
       1508
       +
       amend the last commit like this:

     

       1509
       1509
       +
       

     

       1510
       1510
       +
       ```sh

     

       1511
       1511
       +
       git commit --amend -s

     

       1512
       1512
       +
       ```

     

       1513
       1513
       +
       

     

       1514
       1514
       +
       If you're submitting a PR with multiple commits, make sure each one is

     

       1515
       1515
       +
       signed.

     

       1516
       1516
       +
       

     

       1517
       1517
       +
       For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command

     

       1518
       1518
       +
       to make it sign off commits in the tangled repo:

     

       1519
       1519
       +
       

     

       1520
       1520
       +
       ```shell

     

       1521
       1521
       +
       # Safety check, should say "No matching config key..."

     

       1522
       1522
       +
       jj config list templates.commit_trailers

     

       1523
       1523
       +
       # The command below may need to be adjusted if the command above returned something.

     

       1524
       1524
       +
       jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)"

     

       1525
       1525
       +
       ```

     

       1526
       1526
       +
       

     

       1527
       1527
       +
       Refer to the [jujutsu

     

       1528
       1528
       +
       documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers)

     

       1529
       1529
       +
       for more information.

-136

docs/contributing.md

···

       1
       1
       -
       # tangled contributing guide

     

       2
       2
       -
       

     

       3
       3
       -
       ## commit guidelines

     

       4
       4
       -
       

     

       5
       5
       -
       We follow a commit style similar to the Go project. Please keep commits:

     

       6
       6
       -
       

     

       7
       7
       -
       * **atomic**: each commit should represent one logical change

     

       8
       8
       -
       * **descriptive**: the commit message should clearly describe what the

     

       9
       9
       -
       change does and why it's needed

     

       10
       10
       -
       

     

       11
       11
       -
       ### message format

     

       12
       12
       -
       

     

       13
       13
       -
       ```

     

       14
       14
       -
       <service/top-level directory>/<affected package/directory>: <short summary of change>

     

       15
       15
       -
       

     

       16
       16
       -
       

     

       17
       17
       -
       Optional longer description can go here, if necessary. Explain what the

     

       18
       18
       -
       change does and why, especially if not obvious. Reference relevant

     

       19
       19
       -
       issues or PRs when applicable. These can be links for now since we don't

     

       20
       20
       -
       auto-link issues/PRs yet.

     

       21
       21
       -
       ```

     

       22
       22
       -
       

     

       23
       23
       -
       Here are some examples:

     

       24
       24
       -
       

     

       25
       25
       -
       ```

     

       26
       26
       -
       appview/state: fix token expiry check in middleware

     

       27
       27
       -
       

     

       28
       28
       -
       The previous check did not account for clock drift, leading to premature

     

       29
       29
       -
       token invalidation.

     

       30
       30
       -
       ```

     

       31
       31
       -
       

     

       32
       32
       -
       ```

     

       33
       33
       -
       knotserver/git/service: improve error checking in upload-pack

     

       34
       34
       -
       ```

     

       35
       35
       -
       

     

       36
       36
       -
       

     

       37
       37
       -
       ### general notes

     

       38
       38
       -
       

     

       39
       39
       -
       - PRs get merged "as-is" (fast-forward) -- like applying a patch-series

     

       40
       40
       -
       using `git am`. At present, there is no squashing -- so please author

     

       41
       41
       -
       your commits as they would appear on `master`, following the above

     

       42
       42
       -
       guidelines.

     

       43
       43
       -
       - If there is a lot of nesting, for example "appview:

     

       44
       44
       -
       pages/templates/repo/fragments: ...", these can be truncated down to

     

       45
       45
       -
       just "appview: repo/fragments: ...". If the change affects a lot of

     

       46
       46
       -
       subdirectories, you may abbreviate to just the top-level names, e.g.

     

       47
       47
       -
       "appview: ..." or "knotserver: ...".

     

       48
       48
       -
       - Keep commits lowercased with no trailing period.

     

       49
       49
       -
       - Use the imperative mood in the summary line (e.g., "fix bug" not

     

       50
       50
       -
       "fixed bug" or "fixes bug").

     

       51
       51
       -
       - Try to keep the summary line under 72 characters, but we aren't too

     

       52
       52
       -
       fussed about this.

     

       53
       53
       -
       - Follow the same formatting for PR titles if filled manually.

     

       54
       54
       -
       - Don't include unrelated changes in the same commit.

     

       55
       55
       -
       - Avoid noisy commit messages like "wip" or "final fix"—rewrite history

     

       56
       56
       -
       before submitting if necessary.

     

       57
       57
       -
       

     

       58
       58
       -
       ## code formatting

     

       59
       59
       -
       

     

       60
       60
       -
       We use a variety of tools to format our code, and multiplex them with

     

       61
       61
       -
       [`treefmt`](https://treefmt.com): all you need to do to format your changes

     

       62
       62
       -
       is run `nix run .#fmt` (or just `treefmt` if you're in the devshell).

     

       63
       63
       -
       

     

       64
       64
       -
       ## proposals for bigger changes

     

       65
       65
       -
       

     

       66
       66
       -
       Small fixes like typos, minor bugs, or trivial refactors can be

     

       67
       67
       -
       submitted directly as PRs.

     

       68
       68
       -
       

     

       69
       69
       -
       For larger changes—especially those introducing new features, significant

     

       70
       70
       -
       refactoring, or altering system behavior—please open a proposal first. This

     

       71
       71
       -
       helps us evaluate the scope, design, and potential impact before implementation.

     

       72
       72
       -
       

     

       73
       73
       -
       ### proposal format

     

       74
       74
       -
       

     

       75
       75
       -
       Create a new issue titled:

     

       76
       76
       -
       

     

       77
       77
       -
       ```

     

       78
       78
       -
       proposal: <affected scope>: <summary of change>

     

       79
       79
       -
       ```

     

       80
       80
       -
       

     

       81
       81
       -
       In the description, explain:

     

       82
       82
       -
       

     

       83
       83
       -
       - What the change is

     

       84
       84
       -
       - Why it's needed

     

       85
       85
       -
       - How you plan to implement it (roughly)

     

       86
       86
       -
       - Any open questions or tradeoffs

     

       87
       87
       -
       

     

       88
       88
       -
       We'll use the issue thread to discuss and refine the idea before moving

     

       89
       89
       -
       forward.

     

       90
       90
       -
       

     

       91
       91
       -
       ## developer certificate of origin (DCO)

     

       92
       92
       -
       

     

       93
       93
       -
       We require all contributors to certify that they have the right to

     

       94
       94
       -
       submit the code they're contributing. To do this, we follow the

     

       95
       95
       -
       [Developer Certificate of Origin

     

       96
       96
       -
       (DCO)](https://developercertificate.org/).

     

       97
       97
       -
       

     

       98
       98
       -
       By signing your commits, you're stating that the contribution is your

     

       99
       99
       -
       own work, or that you have the right to submit it under the project's

     

       100
       100
       -
       license. This helps us keep things clean and legally sound.

     

       101
       101
       -
       

     

       102
       102
       -
       To sign your commit, just add the `-s` flag when committing:

     

       103
       103
       -
       

     

       104
       104
       -
       ```sh

     

       105
       105
       -
       git commit -s -m "your commit message"

     

       106
       106
       -
       ```

     

       107
       107
       -
       

     

       108
       108
       -
       This appends a line like:

     

       109
       109
       -
       

     

       110
       110
       -
       ```

     

       111
       111
       -
       Signed-off-by: Your Name <your.email@example.com>

     

       112
       112
       -
       ```

     

       113
       113
       -
       

     

       114
       114
       -
       We won't merge commits if they aren't signed off. If you forget, you can

     

       115
       115
       -
       amend the last commit like this:

     

       116
       116
       -
       

     

       117
       117
       -
       ```sh

     

       118
       118
       -
       git commit --amend -s

     

       119
       119
       -
       ```

     

       120
       120
       -
       

     

       121
       121
       -
       If you're submitting a PR with multiple commits, make sure each one is

     

       122
       122
       -
       signed.

     

       123
       123
       -
       

     

       124
       124
       -
       For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command

     

       125
       125
       -
       to make it sign off commits in the tangled repo:

     

       126
       126
       -
       

     

       127
       127
       -
       ```shell

     

       128
       128
       -
       # Safety check, should say "No matching config key..."

     

       129
       129
       -
       jj config list templates.commit_trailers

     

       130
       130
       -
       # The command below may need to be adjusted if the command above returned something.

     

       131
       131
       -
       jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)"

     

       132
       132
       -
       ```

     

       133
       133
       -
       

     

       134
       134
       -
       Refer to the [jj

     

       135
       135
       -
       documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers)

     

       136
       136
       -
       for more information.

-172

docs/hacking.md

···

       1
       1
       -
       # hacking on tangled

     

       2
       2
       -
       

     

       3
       3
       -
       We highly recommend [installing

     

       4
       4
       -
       nix](https://nixos.org/download/) (the package manager)

     

       5
       5
       -
       before working on the codebase. The nix flake provides a lot

     

       6
       6
       -
       of helpers to get started and most importantly, builds and

     

       7
       7
       -
       dev shells are entirely deterministic.

     

       8
       8
       -
       

     

       9
       9
       -
       To set up your dev environment:

     

       10
       10
       -
       

     

       11
       11
       -
       ```bash

     

       12
       12
       -
       nix develop

     

       13
       13
       -
       ```

     

       14
       14
       -
       

     

       15
       15
       -
       Non-nix users can look at the `devShell` attribute in the

     

       16
       16
       -
       `flake.nix` file to determine necessary dependencies.

     

       17
       17
       -
       

     

       18
       18
       -
       ## running the appview

     

       19
       19
       -
       

     

       20
       20
       -
       The nix flake also exposes a few `app` attributes (run `nix

     

       21
       21
       -
       flake show` to see a full list of what the flake provides),

     

       22
       22
       -
       one of the apps runs the appview with the `air`

     

       23
       23
       -
       live-reloader:

     

       24
       24
       -
       

     

       25
       25
       -
       ```bash

     

       26
       26
       -
       TANGLED_DEV=true nix run .#watch-appview

     

       27
       27
       -
       

     

       28
       28
       -
       # TANGLED_DB_PATH might be of interest to point to

     

       29
       29
       -
       # different sqlite DBs

     

       30
       30
       -
       

     

       31
       31
       -
       # in a separate shell, you can live-reload tailwind

     

       32
       32
       -
       nix run .#watch-tailwind

     

       33
       33
       -
       ```

     

       34
       34
       -
       

     

       35
       35
       -
       To authenticate with the appview, you will need redis and

     

       36
       36
       -
       OAUTH JWKs to be setup:

     

       37
       37
       -
       

     

       38
       38
       -
       ```

     

       39
       39
       -
       # oauth jwks should already be setup by the nix devshell:

     

       40
       40
       -
       echo $TANGLED_OAUTH_CLIENT_SECRET

     

       41
       41
       -
       z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc

     

       42
       42
       -
       

     

       43
       43
       -
       echo $TANGLED_OAUTH_CLIENT_KID

     

       44
       44
       -
       1761667908

     

       45
       45
       -
       

     

       46
       46
       -
       # if not, you can set it up yourself:

     

       47
       47
       -
       goat key generate -t P-256

     

       48
       48
       -
       Key Type: P-256 / secp256r1 / ES256 private key

     

       49
       49
       -
       Secret Key (Multibase Syntax): save this securely (eg, add to password manager)

     

       50
       50
       -
               z42tuPDKRfM2mz2Kv953ARen2jmrPA8S9LX9tRq4RVcUMwwL

     

       51
       51
       -
       Public Key (DID Key Syntax): share or publish this (eg, in DID document)

     

       52
       52
       -
               did:key:zDnaeUBxtG6Xuv3ATJE4GaWeyXM3jyamJsZw3bSPpxx4bNXDR

     

       53
       53
       -
       

     

       54
       54
       -
       # the secret key from above

     

       55
       55
       -
       export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..."

     

       56
       56
       -
       

     

       57
       57
       -
       # run redis in at a new shell to store oauth sessions

     

       58
       58
       -
       redis-server

     

       59
       59
       -
       ```

     

       60
       60
       -
       

     

       61
       61
       -
       ## running knots and spindles

     

       62
       62
       -
       

     

       63
       63
       -
       An end-to-end knot setup requires setting up a machine with

     

       64
       64
       -
       `sshd`, `AuthorizedKeysCommand`, and git user, which is

     

       65
       65
       -
       quite cumbersome. So the nix flake provides a

     

       66
       66
       -
       `nixosConfiguration` to do so.

     

       67
       67
       -
       

     

       68
       68
       -
       <details>

     

       69
       69
       -
         <summary><strong>MacOS users will have to setup a Nix Builder first</strong></summary>

     

       70
       70
       -
       

     

       71
       71
       -
         In order to build Tangled's dev VM on macOS, you will

     

       72
       72
       -
         first need to set up a Linux Nix builder. The recommended

     

       73
       73
       -
         way to do so is to run a [`darwin.linux-builder`

     

       74
       74
       -
         VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)

     

       75
       75
       -
         and to register it in `nix.conf` as a builder for Linux

     

       76
       76
       -
         with the same architecture as your Mac (`linux-aarch64` if

     

       77
       77
       -
         you are using Apple Silicon).

     

       78
       78
       -
       

     

       79
       79
       -
         > IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside

     

       80
       80
       -
         > the tangled repo so that it doesn't conflict with the other VM. For example,

     

       81
       81
       -
         > you can do

     

       82
       82
       -
         >

     

       83
       83
       -
         > ```shell

     

       84
       84
       -
         > cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder

     

       85
       85
       -
         > ```

     

       86
       86
       -
         >

     

       87
       87
       -
         > to store the builder VM in a temporary dir.

     

       88
       88
       -
         >

     

       89
       89
       -
         > You should read and follow [all the other intructions][darwin builder vm] to

     

       90
       90
       -
         >  avoid subtle problems.

     

       91
       91
       -
       

     

       92
       92
       -
         Alternatively, you can use any other method to set up a

     

       93
       93
       -
         Linux machine with `nix` installed that you can `sudo ssh`

     

       94
       94
       -
         into (in other words, root user on your Mac has to be able

     

       95
       95
       -
         to ssh into the Linux machine without entering a password)

     

       96
       96
       -
         and that has the same architecture as your Mac. See

     

       97
       97
       -
         [remote builder

     

       98
       98
       -
         instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)

     

       99
       99
       -
         for how to register such a builder in `nix.conf`.

     

       100
       100
       -
       

     

       101
       101
       -
         > WARNING: If you'd like to use

     

       102
       102
       -
         > [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or

     

       103
       103
       -
         > [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo

     

       104
       104
       -
         > ssh` works can be tricky. It seems to be [possible with

     

       105
       105
       -
         > Orbstack](https://github.com/orgs/orbstack/discussions/1669).

     

       106
       106
       -
       

     

       107
       107
       -
       </details>

     

       108
       108
       -
       

     

       109
       109
       -
       To begin, grab your DID from http://localhost:3000/settings.

     

       110
       110
       -
       Then, set `TANGLED_VM_KNOT_OWNER` and

     

       111
       111
       -
       `TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a

     

       112
       112
       -
       lightweight NixOS VM like so:

     

       113
       113
       -
       

     

       114
       114
       -
       ```bash

     

       115
       115
       -
       nix run --impure .#vm

     

       116
       116
       -
       

     

       117
       117
       -
       # type `poweroff` at the shell to exit the VM

     

       118
       118
       -
       ```

     

       119
       119
       -
       

     

       120
       120
       -
       This starts a knot on port 6444, a spindle on port 6555

     

       121
       121
       -
       with `ssh` exposed on port 2222.

     

       122
       122
       -
       

     

       123
       123
       -
       Once the services are running, head to

     

       124
       124
       -
       http://localhost:3000/settings/knots and hit verify. It should

     

       125
       125
       -
       verify the ownership of the services instantly if everything

     

       126
       126
       -
       went smoothly.

     

       127
       127
       -
       

     

       128
       128
       -
       You can push repositories to this VM with this ssh config

     

       129
       129
       -
       block on your main machine:

     

       130
       130
       -
       

     

       131
       131
       -
       ```bash

     

       132
       132
       -
       Host nixos-shell

     

       133
       133
       -
           Hostname localhost

     

       134
       134
       -
           Port 2222

     

       135
       135
       -
           User git

     

       136
       136
       -
           IdentityFile ~/.ssh/my_tangled_key

     

       137
       137
       -
       ```

     

       138
       138
       -
       

     

       139
       139
       -
       Set up a remote called `local-dev` on a git repo:

     

       140
       140
       -
       

     

       141
       141
       -
       ```bash

     

       142
       142
       -
       git remote add local-dev git@nixos-shell:user/repo

     

       143
       143
       -
       git push local-dev main

     

       144
       144
       -
       ```

     

       145
       145
       -
       

     

       146
       146
       -
       ### running a spindle

     

       147
       147
       -
       

     

       148
       148
       -
       The above VM should already be running a spindle on

     

       149
       149
       -
       `localhost:6555`. Head to http://localhost:3000/settings/spindles and

     

       150
       150
       -
       hit verify. You can then configure each repository to use

     

       151
       151
       -
       this spindle and run CI jobs.

     

       152
       152
       -
       

     

       153
       153
       -
       Of interest when debugging spindles:

     

       154
       154
       -
       

     

       155
       155
       -
       ```

     

       156
       156
       -
       # service logs from journald:

     

       157
       157
       -
       journalctl -xeu spindle

     

       158
       158
       -
       

     

       159
       159
       -
       # CI job logs from disk:

     

       160
       160
       -
       ls /var/log/spindle

     

       161
       161
       -
       

     

       162
       162
       -
       # debugging spindle db:

     

       163
       163
       -
       sqlite3 /var/lib/spindle/spindle.db

     

       164
       164
       -
       

     

       165
       165
       -
       # litecli has a nicer REPL interface:

     

       166
       166
       -
       litecli /var/lib/spindle/spindle.db

     

       167
       167
       -
       ```

     

       168
       168
       -
       

     

       169
       169
       -
       If for any reason you wish to disable either one of the

     

       170
       170
       -
       services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set

     

       171
       171
       -
       `services.tangled.spindle.enable` (or

     

       172
       172
       -
       `services.tangled.knot.enable`) to `false`.

+93

docs/highlight.theme

···

       1
       1
       +
       {

     

       2
       2
       +
           "text-color": null,

     

       3
       3
       +
           "background-color": null,

     

       4
       4
       +
           "line-number-color": null,

     

       5
       5
       +
           "line-number-background-color": null,

     

       6
       6
       +
           "text-styles": {

     

       7
       7
       +
               "Annotation": {

     

       8
       8
       +
                   "text-color": null,

     

       9
       9
       +
                   "background-color": null,

     

       10
       10
       +
                   "bold": false,

     

       11
       11
       +
                   "italic": true,

     

       12
       12
       +
                   "underline": false

     

       13
       13
       +
               },

     

       14
       14
       +
               "ControlFlow": {

     

       15
       15
       +
                   "text-color": null,

     

       16
       16
       +
                   "background-color": null,

     

       17
       17
       +
                   "bold": true,

     

       18
       18
       +
                   "italic": false,

     

       19
       19
       +
                   "underline": false

     

       20
       20
       +
               },

     

       21
       21
       +
               "Error": {

     

       22
       22
       +
                   "text-color": null,

     

       23
       23
       +
                   "background-color": null,

     

       24
       24
       +
                   "bold": true,

     

       25
       25
       +
                   "italic": false,

     

       26
       26
       +
                   "underline": false

     

       27
       27
       +
               },

     

       28
       28
       +
               "Alert": {

     

       29
       29
       +
                   "text-color": null,

     

       30
       30
       +
                   "background-color": null,

     

       31
       31
       +
                   "bold": true,

     

       32
       32
       +
                   "italic": false,

     

       33
       33
       +
                   "underline": false

     

       34
       34
       +
               },

     

       35
       35
       +
               "Preprocessor": {

     

       36
       36
       +
                   "text-color": null,

     

       37
       37
       +
                   "background-color": null,

     

       38
       38
       +
                   "bold": true,

     

       39
       39
       +
                   "italic": false,

     

       40
       40
       +
                   "underline": false

     

       41
       41
       +
               },

     

       42
       42
       +
               "Information": {

     

       43
       43
       +
                   "text-color": null,

     

       44
       44
       +
                   "background-color": null,

     

       45
       45
       +
                   "bold": false,

     

       46
       46
       +
                   "italic": true,

     

       47
       47
       +
                   "underline": false

     

       48
       48
       +
               },

     

       49
       49
       +
               "Warning": {

     

       50
       50
       +
                   "text-color": null,

     

       51
       51
       +
                   "background-color": null,

     

       52
       52
       +
                   "bold": false,

     

       53
       53
       +
                   "italic": true,

     

       54
       54
       +
                   "underline": false

     

       55
       55
       +
               },

     

       56
       56
       +
               "Documentation": {

     

       57
       57
       +
                   "text-color": null,

     

       58
       58
       +
                   "background-color": null,

     

       59
       59
       +
                   "bold": false,

     

       60
       60
       +
                   "italic": true,

     

       61
       61
       +
                   "underline": false

     

       62
       62
       +
               },

     

       63
       63
       +
               "DataType": {

     

       64
       64
       +
                   "text-color": "#8f4e8b",

     

       65
       65
       +
                   "background-color": null,

     

       66
       66
       +
                   "bold": false,

     

       67
       67
       +
                   "italic": false,

     

       68
       68
       +
                   "underline": false

     

       69
       69
       +
               },

     

       70
       70
       +
               "Comment": {

     

       71
       71
       +
                   "text-color": null,

     

       72
       72
       +
                   "background-color": null,

     

       73
       73
       +
                   "bold": false,

     

       74
       74
       +
                   "italic": true,

     

       75
       75
       +
                   "underline": false

     

       76
       76
       +
               },

     

       77
       77
       +
               "CommentVar": {

     

       78
       78
       +
                   "text-color": null,

     

       79
       79
       +
                   "background-color": null,

     

       80
       80
       +
                   "bold": false,

     

       81
       81
       +
                   "italic": true,

     

       82
       82
       +
                   "underline": false

     

       83
       83
       +
               },

     

       84
       84
       +
               "Keyword": {

     

       85
       85
       +
                   "text-color": null,

     

       86
       86
       +
                   "background-color": null,

     

       87
       87
       +
                   "bold": true,

     

       88
       88
       +
                   "italic": false,

     

       89
       89
       +
                   "underline": false

     

       90
       90
       +
               }

     

       91
       91
       +
           }

     

       92
       92
       +
       }

     

       93
       93
       +

-214

docs/knot-hosting.md

···

       1
       1
       -
       # knot self-hosting guide

     

       2
       2
       -
       

     

       3
       3
       -
       So you want to run your own knot server? Great! Here are a few prerequisites:

     

       4
       4
       -
       

     

       5
       5
       -
       1. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux distribution of some kind.

     

       6
       6
       -
       2. A (sub)domain name. People generally use `knot.example.com`.

     

       7
       7
       -
       3. A valid SSL certificate for your domain.

     

       8
       8
       -
       

     

       9
       9
       -
       There's a couple of ways to get started:

     

       10
       10
       -
       * NixOS: refer to

     

       11
       11
       -
       [flake.nix](https://tangled.sh/@tangled.sh/core/blob/master/flake.nix)

     

       12
       12
       -
       * Docker: Documented at

     

       13
       13
       -
       [@tangled.sh/knot-docker](https://tangled.sh/@tangled.sh/knot-docker)

     

       14
       14
       -
       (community maintained: support is not guaranteed!)

     

       15
       15
       -
       * Manual: Documented below.

     

       16
       16
       -
       

     

       17
       17
       -
       ## manual setup

     

       18
       18
       -
       

     

       19
       19
       -
       First, clone this repository:

     

       20
       20
       -
       

     

       21
       21
       -
       ```

     

       22
       22
       -
       git clone https://tangled.org/@tangled.org/core

     

       23
       23
       -
       ```

     

       24
       24
       -
       

     

       25
       25
       -
       Then, build the `knot` CLI. This is the knot administration and operation tool.

     

       26
       26
       -
       For the purpose of this guide, we're only concerned with these subcommands:

     

       27
       27
       -
       

     

       28
       28
       -
       * `knot server`: the main knot server process, typically run as a

     

       29
       29
       -
       supervised service

     

       30
       30
       -
       * `knot guard`: handles role-based access control for git over SSH

     

       31
       31
       -
       (you'll never have to run this yourself)

     

       32
       32
       -
       * `knot keys`: fetches SSH keys associated with your knot; we'll use

     

       33
       33
       -
       this to generate the SSH `AuthorizedKeysCommand`

     

       34
       34
       -
       

     

       35
       35
       -
       ```

     

       36
       36
       -
       cd core

     

       37
       37
       -
       export CGO_ENABLED=1

     

       38
       38
       -
       go build -o knot ./cmd/knot

     

       39
       39
       -
       ```

     

       40
       40
       -
       

     

       41
       41
       -
       Next, move the `knot` binary to a location owned by `root` --

     

       42
       42
       -
       `/usr/local/bin/` is a good choice. Make sure the binary itself is also owned by `root`:

     

       43
       43
       -
       

     

       44
       44
       -
       ```

     

       45
       45
       -
       sudo mv knot /usr/local/bin/knot

     

       46
       46
       -
       sudo chown root:root /usr/local/bin/knot

     

       47
       47
       -
       ```

     

       48
       48
       -
       

     

       49
       49
       -
       This is necessary because SSH `AuthorizedKeysCommand` requires [really

     

       50
       50
       -
       specific permissions](https://stackoverflow.com/a/27638306). The

     

       51
       51
       -
       `AuthorizedKeysCommand` specifies a command that is run by `sshd` to

     

       52
       52
       -
       retrieve a user's public SSH keys dynamically for authentication. Let's

     

       53
       53
       -
       set that up.

     

       54
       54
       -
       

     

       55
       55
       -
       ```

     

       56
       56
       -
       sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF

     

       57
       57
       -
       Match User git

     

       58
       58
       -
         AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys

     

       59
       59
       -
         AuthorizedKeysCommandUser nobody

     

       60
       60
       -
       EOF

     

       61
       61
       -
       ```

     

       62
       62
       -
       

     

       63
       63
       -
       Then, reload `sshd`:

     

       64
       64
       -
       

     

       65
       65
       -
       ```

     

       66
       66
       -
       sudo systemctl reload ssh

     

       67
       67
       -
       ```

     

       68
       68
       -
       

     

       69
       69
       -
       Next, create the `git` user. We'll use the `git` user's home directory

     

       70
       70
       -
       to store repositories:

     

       71
       71
       -
       

     

       72
       72
       -
       ```

     

       73
       73
       -
       sudo adduser git

     

       74
       74
       -
       ```

     

       75
       75
       -
       

     

       76
       76
       -
       Create `/home/git/.knot.env` with the following, updating the values as

     

       77
       77
       -
       necessary. The `KNOT_SERVER_OWNER` should be set to your

     

       78
       78
       -
       DID, you can find your DID in the [Settings](https://tangled.sh/settings) page.

     

       79
       79
       -
       

     

       80
       80
       -
       ```

     

       81
       81
       -
       KNOT_REPO_SCAN_PATH=/home/git

     

       82
       82
       -
       KNOT_SERVER_HOSTNAME=knot.example.com

     

       83
       83
       -
       APPVIEW_ENDPOINT=https://tangled.sh

     

       84
       84
       -
       KNOT_SERVER_OWNER=did:plc:foobar

     

       85
       85
       -
       KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444

     

       86
       86
       -
       KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555

     

       87
       87
       -
       ```

     

       88
       88
       -
       

     

       89
       89
       -
       If you run a Linux distribution that uses systemd, you can use the provided

     

       90
       90
       -
       service file to run the server. Copy

     

       91
       91
       -
       [`knotserver.service`](/systemd/knotserver.service)

     

       92
       92
       -
       to `/etc/systemd/system/`. Then, run:

     

       93
       93
       -
       

     

       94
       94
       -
       ```

     

       95
       95
       -
       systemctl enable knotserver

     

       96
       96
       -
       systemctl start knotserver

     

       97
       97
       -
       ```

     

       98
       98
       -
       

     

       99
       99
       -
       The last step is to configure a reverse proxy like Nginx or Caddy to front your

     

       100
       100
       -
       knot. Here's an example configuration for Nginx:

     

       101
       101
       -
       

     

       102
       102
       -
       ```

     

       103
       103
       -
       server {

     

       104
       104
       -
           listen 80;

     

       105
       105
       -
           listen [::]:80;

     

       106
       106
       -
           server_name knot.example.com;

     

       107
       107
       -
       

     

       108
       108
       -
           location / {

     

       109
       109
       -
               proxy_pass http://localhost:5555;

     

       110
       110
       -
               proxy_set_header Host $host;

     

       111
       111
       -
               proxy_set_header X-Real-IP $remote_addr;

     

       112
       112
       -
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

     

       113
       113
       -
               proxy_set_header X-Forwarded-Proto $scheme;

     

       114
       114
       -
           }

     

       115
       115
       -
       

     

       116
       116
       -
           # wss endpoint for git events

     

       117
       117
       -
           location /events {

     

       118
       118
       -
               proxy_set_header   X-Forwarded-For $remote_addr;

     

       119
       119
       -
               proxy_set_header   Host $http_host;

     

       120
       120
       -
               proxy_set_header Upgrade websocket;

     

       121
       121
       -
               proxy_set_header Connection Upgrade;

     

       122
       122
       -
               proxy_pass http://localhost:5555;

     

       123
       123
       -
           }

     

       124
       124
       -
         # additional config for SSL/TLS go here.

     

       125
       125
       -
       }

     

       126
       126
       -
       

     

       127
       127
       -
       ```

     

       128
       128
       -
       

     

       129
       129
       -
       Remember to use Let's Encrypt or similar to procure a certificate for your

     

       130
       130
       -
       knot domain.

     

       131
       131
       -
       

     

       132
       132
       -
       You should now have a running knot server! You can finalize

     

       133
       133
       -
       your registration by hitting the `verify` button on the

     

       134
       134
       -
       [/settings/knots](https://tangled.org/settings/knots) page. This simply creates

     

       135
       135
       -
       a record on your PDS to announce the existence of the knot.

     

       136
       136
       -
       

     

       137
       137
       -
       ### custom paths

     

       138
       138
       -
       

     

       139
       139
       -
       (This section applies to manual setup only. Docker users should edit the mounts

     

       140
       140
       -
       in `docker-compose.yml` instead.)

     

       141
       141
       -
       

     

       142
       142
       -
       Right now, the database and repositories of your knot lives in `/home/git`. You

     

       143
       143
       -
       can move these paths if you'd like to store them in another folder. Be careful

     

       144
       144
       -
       when adjusting these paths:

     

       145
       145
       -
       

     

       146
       146
       -
       * Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent

     

       147
       147
       -
       any possible side effects. Remember to restart it once you're done.

     

       148
       148
       -
       * Make backups before moving in case something goes wrong.

     

       149
       149
       -
       * Make sure the `git` user can read and write from the new paths.

     

       150
       150
       -
       

     

       151
       151
       -
       #### database

     

       152
       152
       -
       

     

       153
       153
       -
       As an example, let's say the current database is at `/home/git/knotserver.db`,

     

       154
       154
       -
       and we want to move it to `/home/git/database/knotserver.db`.

     

       155
       155
       -
       

     

       156
       156
       -
       Copy the current database to the new location. Make sure to copy the `.db-shm`

     

       157
       157
       -
       and `.db-wal` files if they exist.

     

       158
       158
       -
       

     

       159
       159
       -
       ```

     

       160
       160
       -
       mkdir /home/git/database

     

       161
       161
       -
       cp /home/git/knotserver.db* /home/git/database

     

       162
       162
       -
       ```

     

       163
       163
       -
       

     

       164
       164
       -
       In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to

     

       165
       165
       -
       the new file path (_not_ the directory):

     

       166
       166
       -
       

     

       167
       167
       -
       ```

     

       168
       168
       -
       KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db

     

       169
       169
       -
       ```

     

       170
       170
       -
       

     

       171
       171
       -
       #### repositories

     

       172
       172
       -
       

     

       173
       173
       -
       As an example, let's say the repositories are currently in `/home/git`, and we

     

       174
       174
       -
       want to move them into `/home/git/repositories`.

     

       175
       175
       -
       

     

       176
       176
       -
       Create the new folder, then move the existing repositories (if there are any):

     

       177
       177
       -
       

     

       178
       178
       -
       ```

     

       179
       179
       -
       mkdir /home/git/repositories

     

       180
       180
       -
       # move all DIDs into the new folder; these will vary for you!

     

       181
       181
       -
       mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories

     

       182
       182
       -
       ```

     

       183
       183
       -
       

     

       184
       184
       -
       In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH`

     

       185
       185
       -
       to the new directory:

     

       186
       186
       -
       

     

       187
       187
       -
       ```

     

       188
       188
       -
       KNOT_REPO_SCAN_PATH=/home/git/repositories

     

       189
       189
       -
       ```

     

       190
       190
       -
       

     

       191
       191
       -
       Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated

     

       192
       192
       -
       repository path:

     

       193
       193
       -
       

     

       194
       194
       -
       ```

     

       195
       195
       -
       sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF

     

       196
       196
       -
       Match User git

     

       197
       197
       -
         AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories

     

       198
       198
       -
         AuthorizedKeysCommandUser nobody

     

       199
       199
       -
       EOF

     

       200
       200
       -
       ```

     

       201
       201
       -
       

     

       202
       202
       -
       Make sure to restart your SSH server!

     

       203
       203
       -
       

     

       204
       204
       -
       #### MOTD (message of the day)

     

       205
       205
       -
       

     

       206
       206
       -
       To configure the MOTD used ("Welcome to this knot!" by default), edit the

     

       207
       207
       -
       `/home/git/motd` file:

     

       208
       208
       -
       

     

       209
       209
       -
       ```

     

       210
       210
       -
       printf "Hi from this knot!\n" > /home/git/motd

     

       211
       211
       -
       ```

     

       212
       212
       -
       

     

       213
       213
       -
       Note that you should add a newline at the end if setting a non-empty message

     

       214
       214
       -
       since the knot won't do this for you.

-59

docs/migrations.md

···

       1
       1
       -
       # Migrations

     

       2
       2
       -
       

     

       3
       3
       -
       This document is laid out in reverse-chronological order.

     

       4
       4
       -
       Newer migration guides are listed first, and older guides

     

       5
       5
       -
       are further down the page.

     

       6
       6
       -
       

     

       7
       7
       -
       ## Upgrading from v1.8.x

     

       8
       8
       -
       

     

       9
       9
       -
       After v1.8.2, the HTTP API for knot and spindles have been

     

       10
       10
       -
       deprecated and replaced with XRPC. Repositories on outdated

     

       11
       11
       -
       knots will not be viewable from the appview. Upgrading is

     

       12
       12
       -
       straightforward however.

     

       13
       13
       -
       

     

       14
       14
       -
       For knots:

     

       15
       15
       -
       

     

       16
       16
       -
       - Upgrade to latest tag (v1.9.0 or above)

     

       17
       17
       -
       - Head to the [knot dashboard](https://tangled.org/settings/knots) and

     

       18
       18
       -
         hit the "retry" button to verify your knot

     

       19
       19
       -
       

     

       20
       20
       -
       For spindles:

     

       21
       21
       -
       

     

       22
       22
       -
       - Upgrade to latest tag (v1.9.0 or above)

     

       23
       23
       -
       - Head to the [spindle

     

       24
       24
       -
         dashboard](https://tangled.org/settings/spindles) and hit the

     

       25
       25
       -
         "retry" button to verify your spindle

     

       26
       26
       -
       

     

       27
       27
       -
       ## Upgrading from v1.7.x

     

       28
       28
       -
       

     

       29
       29
       -
       After v1.7.0, knot secrets have been deprecated. You no

     

       30
       30
       -
       longer need a secret from the appview to run a knot. All

     

       31
       31
       -
       authorized commands to knots are managed via [Inter-Service

     

       32
       32
       -
       Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).

     

       33
       33
       -
       Knots will be read-only until upgraded.

     

       34
       34
       -
       

     

       35
       35
       -
       Upgrading is quite easy, in essence:

     

       36
       36
       -
       

     

       37
       37
       -
       - `KNOT_SERVER_SECRET` is no more, you can remove this

     

       38
       38
       -
         environment variable entirely

     

       39
       39
       -
       - `KNOT_SERVER_OWNER` is now required on boot, set this to

     

       40
       40
       -
         your DID. You can find your DID in the

     

       41
       41
       -
         [settings](https://tangled.org/settings) page.

     

       42
       42
       -
       - Restart your knot once you have replaced the environment

     

       43
       43
       -
         variable

     

       44
       44
       -
       - Head to the [knot dashboard](https://tangled.org/settings/knots) and

     

       45
       45
       -
         hit the "retry" button to verify your knot. This simply

     

       46
       46
       -
         writes a `sh.tangled.knot` record to your PDS.

     

       47
       47
       -
       

     

       48
       48
       -
       If you use the nix module, simply bump the flake to the

     

       49
       49
       -
       latest revision, and change your config block like so:

     

       50
       50
       -
       

     

       51
       51
       -
       ```diff

     

       52
       52
       -
        services.tangled.knot = {

     

       53
       53
       -
          enable = true;

     

       54
       54
       -
          server = {

     

       55
       55
       -
       -    secretFile = /path/to/secret;

     

       56
       56
       -
       +    owner = "did:plc:foo";

     

       57
       57
       -
          };

     

       58
       58
       -
        };

     

       59
       59
       -
       ```

-25

docs/spindle/architecture.md

···

       1
       1
       -
       # spindle architecture

     

       2
       2
       -
       

     

       3
       3
       -
       Spindle is a small CI runner service. Here's a high level overview of how it operates:

     

       4
       4
       -
       

     

       5
       5
       -
       * listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and

     

       6
       6
       -
       [`sh.tangled.repo`](/lexicons/repo.json) records on the Jetstream.

     

       7
       7
       -
       * when a new repo record comes through (typically when you add a spindle to a

     

       8
       8
       -
       repo from the settings), spindle then resolves the underlying knot and

     

       9
       9
       -
       subscribes to repo events (see:

     

       10
       10
       -
       [`sh.tangled.pipeline`](/lexicons/pipeline.json)).

     

       11
       11
       -
       * the spindle engine then handles execution of the pipeline, with results and

     

       12
       12
       -
       logs beamed on the spindle event stream over wss

     

       13
       13
       -
       

     

       14
       14
       -
       ### the engine

     

       15
       15
       -
       

     

       16
       16
       -
       At present, the only supported backend is Docker (and Podman, if Docker

     

       17
       17
       -
       compatibility is enabled, so that `/run/docker.sock` is created). Spindle

     

       18
       18
       -
       executes each step in the pipeline in a fresh container, with state persisted

     

       19
       19
       -
       across steps within the `/tangled/workspace` directory.

     

       20
       20
       -
       

     

       21
       21
       -
       The base image for the container is constructed on the fly using

     

       22
       22
       -
       [Nixery](https://nixery.dev), which is handy for caching layers for frequently

     

       23
       23
       -
       used packages.

     

       24
       24
       -
       

     

       25
       25
       -
       The pipeline manifest is [specified here](/docs/spindle/pipeline.md).

-52

docs/spindle/hosting.md

···

       1
       1
       -
       # spindle self-hosting guide

     

       2
       2
       -
       

     

       3
       3
       -
       ## prerequisites

     

       4
       4
       -
       

     

       5
       5
       -
       * Go

     

       6
       6
       -
       * Docker (the only supported backend currently)

     

       7
       7
       -
       

     

       8
       8
       -
       ## configuration

     

       9
       9
       -
       

     

       10
       10
       -
       Spindle is configured using environment variables. The following environment variables are available:

     

       11
       11
       -
       

     

       12
       12
       -
       * `SPINDLE_SERVER_LISTEN_ADDR`: The address the server listens on (default: `"0.0.0.0:6555"`).

     

       13
       13
       -
       * `SPINDLE_SERVER_DB_PATH`: The path to the SQLite database file (default: `"spindle.db"`).

     

       14
       14
       -
       * `SPINDLE_SERVER_HOSTNAME`: The hostname of the server (required).

     

       15
       15
       -
       * `SPINDLE_SERVER_JETSTREAM_ENDPOINT`: The endpoint of the Jetstream server (default: `"wss://jetstream1.us-west.bsky.network/subscribe"`).

     

       16
       16
       -
       * `SPINDLE_SERVER_DEV`: A boolean indicating whether the server is running in development mode (default: `false`).

     

       17
       17
       -
       * `SPINDLE_SERVER_OWNER`: The DID of the owner (required).

     

       18
       18
       -
       * `SPINDLE_PIPELINES_NIXERY`: The Nixery URL (default: `"nixery.tangled.sh"`).

     

       19
       19
       -
       * `SPINDLE_PIPELINES_WORKFLOW_TIMEOUT`: The default workflow timeout (default: `"5m"`).

     

       20
       20
       -
       * `SPINDLE_PIPELINES_LOG_DIR`: The directory to store workflow logs (default: `"/var/log/spindle"`).

     

       21
       21
       -
       

     

       22
       22
       -
       ## running spindle

     

       23
       23
       -
       

     

       24
       24
       -
       1.  **Set the environment variables.**  For example:

     

       25
       25
       -
       

     

       26
       26
       -
           ```shell

     

       27
       27
       -
           export SPINDLE_SERVER_HOSTNAME="your-hostname"

     

       28
       28
       -
           export SPINDLE_SERVER_OWNER="your-did"

     

       29
       29
       -
           ```

     

       30
       30
       -
       

     

       31
       31
       -
       2.  **Build the Spindle binary.**

     

       32
       32
       -
       

     

       33
       33
       -
           ```shell

     

       34
       34
       -
           cd core

     

       35
       35
       -
           go mod download

     

       36
       36
       -
           go build -o cmd/spindle/spindle cmd/spindle/main.go

     

       37
       37
       -
           ```

     

       38
       38
       -
       

     

       39
       39
       -
       3.  **Create the log directory.**

     

       40
       40
       -
       

     

       41
       41
       -
           ```shell

     

       42
       42
       -
           sudo mkdir -p /var/log/spindle

     

       43
       43
       -
           sudo chown $USER:$USER -R /var/log/spindle

     

       44
       44
       -
           ```

     

       45
       45
       -
       

     

       46
       46
       -
       4.  **Run the Spindle binary.**

     

       47
       47
       -
       

     

       48
       48
       -
           ```shell

     

       49
       49
       -
           ./cmd/spindle/spindle

     

       50
       50
       -
           ```

     

       51
       51
       -
       

     

       52
       52
       -
       Spindle will now start, connect to the Jetstream server, and begin processing pipelines.

-285

docs/spindle/openbao.md

···

       1
       1
       -
       # spindle secrets with openbao

     

       2
       2
       -
       

     

       3
       3
       -
       This document covers setting up Spindle to use OpenBao for secrets

     

       4
       4
       -
       management via OpenBao Proxy instead of the default SQLite backend.

     

       5
       5
       -
       

     

       6
       6
       -
       ## overview

     

       7
       7
       -
       

     

       8
       8
       -
       Spindle now uses OpenBao Proxy for secrets management. The proxy handles

     

       9
       9
       -
       authentication automatically using AppRole credentials, while Spindle

     

       10
       10
       -
       connects to the local proxy instead of directly to the OpenBao server.

     

       11
       11
       -
       

     

       12
       12
       -
       This approach provides better security, automatic token renewal, and

     

       13
       13
       -
       simplified application code.

     

       14
       14
       -
       

     

       15
       15
       -
       ## installation

     

       16
       16
       -
       

     

       17
       17
       -
       Install OpenBao from nixpkgs:

     

       18
       18
       -
       

     

       19
       19
       -
       ```bash

     

       20
       20
       -
       nix shell nixpkgs#openbao   # for a local server

     

       21
       21
       -
       ```

     

       22
       22
       -
       

     

       23
       23
       -
       ## setup

     

       24
       24
       -
       

     

       25
       25
       -
       The setup process can is documented for both local development and production.

     

       26
       26
       -
       

     

       27
       27
       -
       ### local development

     

       28
       28
       -
       

     

       29
       29
       -
       Start OpenBao in dev mode:

     

       30
       30
       -
       

     

       31
       31
       -
       ```bash

     

       32
       32
       -
       bao server -dev -dev-root-token-id="root" -dev-listen-address=127.0.0.1:8201

     

       33
       33
       -
       ```

     

       34
       34
       -
       

     

       35
       35
       -
       This starts OpenBao on `http://localhost:8201` with a root token.

     

       36
       36
       -
       

     

       37
       37
       -
       Set up environment for bao CLI:

     

       38
       38
       -
       

     

       39
       39
       -
       ```bash

     

       40
       40
       -
       export BAO_ADDR=http://localhost:8200

     

       41
       41
       -
       export BAO_TOKEN=root

     

       42
       42
       -
       ```

     

       43
       43
       -
       

     

       44
       44
       -
       ### production

     

       45
       45
       -
       

     

       46
       46
       -
       You would typically use a systemd service with a configuration file. Refer to

     

       47
       47
       -
       [@tangled.org/infra](https://tangled.org/@tangled.org/infra) for how this can be

     

       48
       48
       -
       achieved using Nix.

     

       49
       49
       -
       

     

       50
       50
       -
       Then, initialize the bao server:

     

       51
       51
       -
       ```bash

     

       52
       52
       -
       bao operator init -key-shares=1 -key-threshold=1

     

       53
       53
       -
       ```

     

       54
       54
       -
       

     

       55
       55
       -
       This will print out an unseal key and a root key. Save them somewhere (like a password manager). Then unseal the vault to begin setting it up:

     

       56
       56
       -
       ```bash

     

       57
       57
       -
       bao operator unseal <unseal_key>

     

       58
       58
       -
       ```

     

       59
       59
       -
       

     

       60
       60
       -
       All steps below remain the same across both dev and production setups.

     

       61
       61
       -
       

     

       62
       62
       -
       ### configure openbao server

     

       63
       63
       -
       

     

       64
       64
       -
       Create the spindle KV mount:

     

       65
       65
       -
       

     

       66
       66
       -
       ```bash

     

       67
       67
       -
       bao secrets enable -path=spindle -version=2 kv

     

       68
       68
       -
       ```

     

       69
       69
       -
       

     

       70
       70
       -
       Set up AppRole authentication and policy:

     

       71
       71
       -
       

     

       72
       72
       -
       Create a policy file `spindle-policy.hcl`:

     

       73
       73
       -
       

     

       74
       74
       -
       ```hcl

     

       75
       75
       -
       # Full access to spindle KV v2 data

     

       76
       76
       -
       path "spindle/data/*" {

     

       77
       77
       -
         capabilities = ["create", "read", "update", "delete"]

     

       78
       78
       -
       }

     

       79
       79
       -
       

     

       80
       80
       -
       # Access to metadata for listing and management

     

       81
       81
       -
       path "spindle/metadata/*" {

     

       82
       82
       -
         capabilities = ["list", "read", "delete", "update"]

     

       83
       83
       -
       }

     

       84
       84
       -
       

     

       85
       85
       -
       # Allow listing at root level

     

       86
       86
       -
       path "spindle/" {

     

       87
       87
       -
         capabilities = ["list"]

     

       88
       88
       -
       }

     

       89
       89
       -
       

     

       90
       90
       -
       # Required for connection testing and health checks

     

       91
       91
       -
       path "auth/token/lookup-self" {

     

       92
       92
       -
         capabilities = ["read"]

     

       93
       93
       -
       }

     

       94
       94
       -
       ```

     

       95
       95
       -
       

     

       96
       96
       -
       Apply the policy and create an AppRole:

     

       97
       97
       -
       

     

       98
       98
       -
       ```bash

     

       99
       99
       -
       bao policy write spindle-policy spindle-policy.hcl

     

       100
       100
       -
       bao auth enable approle

     

       101
       101
       -
       bao write auth/approle/role/spindle \

     

       102
       102
       -
           token_policies="spindle-policy" \

     

       103
       103
       -
           token_ttl=1h \

     

       104
       104
       -
           token_max_ttl=4h \

     

       105
       105
       -
           bind_secret_id=true \

     

       106
       106
       -
           secret_id_ttl=0 \

     

       107
       107
       -
           secret_id_num_uses=0

     

       108
       108
       -
       ```

     

       109
       109
       -
       

     

       110
       110
       -
       Get the credentials:

     

       111
       111
       -
       

     

       112
       112
       -
       ```bash

     

       113
       113
       -
       # Get role ID (static)

     

       114
       114
       -
       ROLE_ID=$(bao read -field=role_id auth/approle/role/spindle/role-id)

     

       115
       115
       -
       

     

       116
       116
       -
       # Generate secret ID

     

       117
       117
       -
       SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/spindle/secret-id)

     

       118
       118
       -
       

     

       119
       119
       -
       echo "Role ID: $ROLE_ID"

     

       120
       120
       -
       echo "Secret ID: $SECRET_ID"

     

       121
       121
       -
       ```

     

       122
       122
       -
       

     

       123
       123
       -
       ### create proxy configuration

     

       124
       124
       -
       

     

       125
       125
       -
       Create the credential files:

     

       126
       126
       -
       

     

       127
       127
       -
       ```bash

     

       128
       128
       -
       # Create directory for OpenBao files

     

       129
       129
       -
       mkdir -p /tmp/openbao

     

       130
       130
       -
       

     

       131
       131
       -
       # Save credentials

     

       132
       132
       -
       echo "$ROLE_ID" > /tmp/openbao/role-id

     

       133
       133
       -
       echo "$SECRET_ID" > /tmp/openbao/secret-id

     

       134
       134
       -
       chmod 600 /tmp/openbao/role-id /tmp/openbao/secret-id

     

       135
       135
       -
       ```

     

       136
       136
       -
       

     

       137
       137
       -
       Create a proxy configuration file `/tmp/openbao/proxy.hcl`:

     

       138
       138
       -
       

     

       139
       139
       -
       ```hcl

     

       140
       140
       -
       # OpenBao server connection

     

       141
       141
       -
       vault {

     

       142
       142
       -
         address = "http://localhost:8200"

     

       143
       143
       -
       }

     

       144
       144
       -
       

     

       145
       145
       -
       # Auto-Auth using AppRole

     

       146
       146
       -
       auto_auth {

     

       147
       147
       -
         method "approle" {

     

       148
       148
       -
           mount_path = "auth/approle"

     

       149
       149
       -
           config = {

     

       150
       150
       -
             role_id_file_path   = "/tmp/openbao/role-id"

     

       151
       151
       -
             secret_id_file_path = "/tmp/openbao/secret-id"

     

       152
       152
       -
           }

     

       153
       153
       -
         }

     

       154
       154
       -
       

     

       155
       155
       -
         # Optional: write token to file for debugging

     

       156
       156
       -
         sink "file" {

     

       157
       157
       -
           config = {

     

       158
       158
       -
             path = "/tmp/openbao/token"

     

       159
       159
       -
             mode = 0640

     

       160
       160
       -
           }

     

       161
       161
       -
         }

     

       162
       162
       -
       }

     

       163
       163
       -
       

     

       164
       164
       -
       # Proxy listener for Spindle

     

       165
       165
       -
       listener "tcp" {

     

       166
       166
       -
         address     = "127.0.0.1:8201"

     

       167
       167
       -
         tls_disable = true

     

       168
       168
       -
       }

     

       169
       169
       -
       

     

       170
       170
       -
       # Enable API proxy with auto-auth token

     

       171
       171
       -
       api_proxy {

     

       172
       172
       -
         use_auto_auth_token = true

     

       173
       173
       -
       }

     

       174
       174
       -
       

     

       175
       175
       -
       # Enable response caching

     

       176
       176
       -
       cache {

     

       177
       177
       -
         use_auto_auth_token = true

     

       178
       178
       -
       }

     

       179
       179
       -
       

     

       180
       180
       -
       # Logging

     

       181
       181
       -
       log_level = "info"

     

       182
       182
       -
       ```

     

       183
       183
       -
       

     

       184
       184
       -
       ### start the proxy

     

       185
       185
       -
       

     

       186
       186
       -
       Start OpenBao Proxy:

     

       187
       187
       -
       

     

       188
       188
       -
       ```bash

     

       189
       189
       -
       bao proxy -config=/tmp/openbao/proxy.hcl

     

       190
       190
       -
       ```

     

       191
       191
       -
       

     

       192
       192
       -
       The proxy will authenticate with OpenBao and start listening on

     

       193
       193
       -
       `127.0.0.1:8201`.

     

       194
       194
       -
       

     

       195
       195
       -
       ### configure spindle

     

       196
       196
       -
       

     

       197
       197
       -
       Set these environment variables for Spindle:

     

       198
       198
       -
       

     

       199
       199
       -
       ```bash

     

       200
       200
       -
       export SPINDLE_SERVER_SECRETS_PROVIDER=openbao

     

       201
       201
       -
       export SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR=http://127.0.0.1:8201

     

       202
       202
       -
       export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle

     

       203
       203
       -
       ```

     

       204
       204
       -
       

     

       205
       205
       -
       Start Spindle:

     

       206
       206
       -
       

     

       207
       207
       -
       Spindle will now connect to the local proxy, which handles all

     

       208
       208
       -
       authentication automatically.

     

       209
       209
       -
       

     

       210
       210
       -
       ## production setup for proxy

     

       211
       211
       -
       

     

       212
       212
       -
       For production, you'll want to run the proxy as a service:

     

       213
       213
       -
       

     

       214
       214
       -
       Place your production configuration in `/etc/openbao/proxy.hcl` with

     

       215
       215
       -
       proper TLS settings for the vault connection.

     

       216
       216
       -
       

     

       217
       217
       -
       ## verifying setup

     

       218
       218
       -
       

     

       219
       219
       -
       Test the proxy directly:

     

       220
       220
       -
       

     

       221
       221
       -
       ```bash

     

       222
       222
       -
       # Check proxy health

     

       223
       223
       -
       curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/sys/health

     

       224
       224
       -
       

     

       225
       225
       -
       # Test token lookup through proxy

     

       226
       226
       -
       curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/auth/token/lookup-self

     

       227
       227
       -
       ```

     

       228
       228
       -
       

     

       229
       229
       -
       Test OpenBao operations through the server:

     

       230
       230
       -
       

     

       231
       231
       -
       ```bash

     

       232
       232
       -
       # List all secrets

     

       233
       233
       -
       bao kv list spindle/

     

       234
       234
       -
       

     

       235
       235
       -
       # Add a test secret via Spindle API, then check it exists

     

       236
       236
       -
       bao kv list spindle/repos/

     

       237
       237
       -
       

     

       238
       238
       -
       # Get a specific secret

     

       239
       239
       -
       bao kv get spindle/repos/your_repo_path/SECRET_NAME

     

       240
       240
       -
       ```

     

       241
       241
       -
       

     

       242
       242
       -
       ## how it works

     

       243
       243
       -
       

     

       244
       244
       -
       - Spindle connects to OpenBao Proxy on localhost (typically port 8200 or 8201)

     

       245
       245
       -
       - The proxy authenticates with OpenBao using AppRole credentials

     

       246
       246
       -
       - All Spindle requests go through the proxy, which injects authentication tokens

     

       247
       247
       -
       - Secrets are stored at `spindle/repos/{sanitized_repo_path}/{secret_key}`

     

       248
       248
       -
       - Repository paths like `did:plc:alice/myrepo` become `did_plc_alice_myrepo`

     

       249
       249
       -
       - The proxy handles all token renewal automatically

     

       250
       250
       -
       - Spindle no longer manages tokens or authentication directly

     

       251
       251
       -
       

     

       252
       252
       -
       ## troubleshooting

     

       253
       253
       -
       

     

       254
       254
       -
       **Connection refused**: Check that the OpenBao Proxy is running and

     

       255
       255
       -
       listening on the configured address.

     

       256
       256
       -
       

     

       257
       257
       -
       **403 errors**: Verify the AppRole credentials are correct and the policy

     

       258
       258
       -
       has the necessary permissions.

     

       259
       259
       -
       

     

       260
       260
       -
       **404 route errors**: The spindle KV mount probably doesn't exist - run

     

       261
       261
       -
       the mount creation step again.

     

       262
       262
       -
       

     

       263
       263
       -
       **Proxy authentication failures**: Check the proxy logs and verify the

     

       264
       264
       -
       role-id and secret-id files are readable and contain valid credentials.

     

       265
       265
       -
       

     

       266
       266
       -
       **Secret not found after writing**: This can indicate policy permission

     

       267
       267
       -
       issues. Verify the policy includes both `spindle/data/*` and

     

       268
       268
       -
       `spindle/metadata/*` paths with appropriate capabilities.

     

       269
       269
       -
       

     

       270
       270
       -
       Check proxy logs:

     

       271
       271
       -
       

     

       272
       272
       -
       ```bash

     

       273
       273
       -
       # If running as systemd service

     

       274
       274
       -
       journalctl -u openbao-proxy -f

     

       275
       275
       -
       

     

       276
       276
       -
       # If running directly, check the console output

     

       277
       277
       -
       ```

     

       278
       278
       -
       

     

       279
       279
       -
       Test AppRole authentication manually:

     

       280
       280
       -
       

     

       281
       281
       -
       ```bash

     

       282
       282
       -
       bao write auth/approle/login \

     

       283
       283
       -
           role_id="$(cat /tmp/openbao/role-id)" \

     

       284
       284
       -
           secret_id="$(cat /tmp/openbao/secret-id)"

     

       285
       285
       -
       ```

-183

docs/spindle/pipeline.md

···

       1
       1
       -
       # spindle pipelines

     

       2
       2
       -
       

     

       3
       3
       -
       Spindle workflows allow you to write CI/CD pipelines in a simple format. They're located in the `.tangled/workflows` directory at the root of your repository, and are defined using YAML.

     

       4
       4
       -
       

     

       5
       5
       -
       The fields are:

     

       6
       6
       -
       

     

       7
       7
       -
       - [Trigger](#trigger): A **required** field that defines when a workflow should be triggered.

     

       8
       8
       -
       - [Engine](#engine): A **required** field that defines which engine a workflow should run on.

     

       9
       9
       -
       - [Clone options](#clone-options): An **optional** field that defines how the repository should be cloned.

     

       10
       10
       -
       - [Dependencies](#dependencies): An **optional** field that allows you to list dependencies you may need.

     

       11
       11
       -
       - [Environment](#environment): An **optional** field that allows you to define environment variables.

     

       12
       12
       -
       - [Steps](#steps): An **optional** field that allows you to define what steps should run in the workflow.

     

       13
       13
       -
       

     

       14
       14
       -
       ## Trigger

     

       15
       15
       -
       

     

       16
       16
       -
       The first thing to add to a workflow is the trigger, which defines when a workflow runs. This is defined using a `when` field, which takes in a list of conditions. Each condition has the following fields:

     

       17
       17
       -
       

     

       18
       18
       -
       - `event`: This is a **required** field that defines when your workflow should run. It's a list that can take one or more of the following values:

     

       19
       19
       -
         - `push`: The workflow should run every time a commit is pushed to the repository.

     

       20
       20
       -
         - `pull_request`: The workflow should run every time a pull request is made or updated.

     

       21
       21
       -
         - `manual`: The workflow can be triggered manually.

     

       22
       22
       -
       - `branch`: Defines which branches the workflow should run for. If used with the `push` event, commits to the branch(es) listed here will trigger the workflow. If used with the `pull_request` event, updates to pull requests targeting the branch(es) listed here will trigger the workflow. This field has no effect with the `manual` event. Supports glob patterns using `*` and `**` (e.g., `main`, `develop`, `release-*`). Either `branch` or `tag` (or both) must be specified for `push` events.

     

       23
       23
       -
       - `tag`: Defines which tags the workflow should run for. Only used with the `push` event - when tags matching the pattern(s) listed here are pushed, the workflow will trigger. This field has no effect with `pull_request` or `manual` events. Supports glob patterns using `*` and `**` (e.g., `v*`, `v1.*`, `release-**`). Either `branch` or `tag` (or both) must be specified for `push` events.

     

       24
       24
       -
       

     

       25
       25
       -
       For example, if you'd like to define a workflow that runs when commits are pushed to the `main` and `develop` branches, or when pull requests that target the `main` branch are updated, or manually, you can do so with:

     

       26
       26
       -
       

     

       27
       27
       -
       ```yaml

     

       28
       28
       -
       when:

     

       29
       29
       -
         - event: ["push", "manual"]

     

       30
       30
       -
           branch: ["main", "develop"]

     

       31
       31
       -
         - event: ["pull_request"]

     

       32
       32
       -
           branch: ["main"]

     

       33
       33
       -
       ```

     

       34
       34
       -
       

     

       35
       35
       -
       You can also trigger workflows on tag pushes. For instance, to run a deployment workflow when tags matching `v*` are pushed:

     

       36
       36
       -
       

     

       37
       37
       -
       ```yaml

     

       38
       38
       -
       when:

     

       39
       39
       -
         - event: ["push"]

     

       40
       40
       -
           tag: ["v*"]

     

       41
       41
       -
       ```

     

       42
       42
       -
       

     

       43
       43
       -
       You can even combine branch and tag patterns in a single constraint (the workflow triggers if either matches):

     

       44
       44
       -
       

     

       45
       45
       -
       ```yaml

     

       46
       46
       -
       when:

     

       47
       47
       -
         - event: ["push"]

     

       48
       48
       -
           branch: ["main", "release-*"]

     

       49
       49
       -
           tag: ["v*", "stable"]

     

       50
       50
       -
       ```

     

       51
       51
       -
       

     

       52
       52
       -
       ## Engine

     

       53
       53
       -
       

     

       54
       54
       -
       Next is the engine on which the workflow should run, defined using the **required** `engine` field. The currently supported engines are:

     

       55
       55
       -
       

     

       56
       56
       -
       - `nixery`: This uses an instance of [Nixery](https://nixery.dev) to run steps, which allows you to add [dependencies](#dependencies) from [Nixpkgs](https://github.com/NixOS/nixpkgs). You can search for packages on https://search.nixos.org, and there's a pretty good chance the package(s) you're looking for will be there.

     

       57
       57
       -
       

     

       58
       58
       -
       Example:

     

       59
       59
       -
       

     

       60
       60
       -
       ```yaml

     

       61
       61
       -
       engine: "nixery"

     

       62
       62
       -
       ```

     

       63
       63
       -
       

     

       64
       64
       -
       ## Clone options

     

       65
       65
       -
       

     

       66
       66
       -
       When a workflow starts, the first step is to clone the repository. You can customize this behavior using the **optional** `clone` field. It has the following fields:

     

       67
       67
       -
       

     

       68
       68
       -
       - `skip`: Setting this to `true` will skip cloning the repository. This can be useful if your workflow is doing something that doesn't require anything from the repository itself. This is `false` by default.

     

       69
       69
       -
       - `depth`: This sets the number of commits, or the "clone depth", to fetch from the repository. For example, if you set this to 2, the last 2 commits will be fetched. By default, the depth is set to 1, meaning only the most recent commit will be fetched, which is the commit that triggered the workflow.

     

       70
       70
       -
       - `submodules`: If you use [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) in your repository, setting this field to `true` will recursively fetch all submodules. This is `false` by default.

     

       71
       71
       -
       

     

       72
       72
       -
       The default settings are:

     

       73
       73
       -
       

     

       74
       74
       -
       ```yaml

     

       75
       75
       -
       clone:

     

       76
       76
       -
         skip: false

     

       77
       77
       -
         depth: 1

     

       78
       78
       -
         submodules: false

     

       79
       79
       -
       ```

     

       80
       80
       -
       

     

       81
       81
       -
       ## Dependencies

     

       82
       82
       -
       

     

       83
       83
       -
       Usually when you're running a workflow, you'll need additional dependencies. The `dependencies` field lets you define which dependencies to get, and from where. It's a key-value map, with the key being the registry to fetch dependencies from, and the value being the list of dependencies to fetch.

     

       84
       84
       -
       

     

       85
       85
       -
       Say you want to fetch Node.js and Go from `nixpkgs`, and a package called `my_pkg` you've made from your own registry at your repository at `https://tangled.sh/@example.com/my_pkg`. You can define those dependencies like so:

     

       86
       86
       -
       

     

       87
       87
       -
       ```yaml

     

       88
       88
       -
       dependencies:

     

       89
       89
       -
         # nixpkgs

     

       90
       90
       -
         nixpkgs:

     

       91
       91
       -
           - nodejs

     

       92
       92
       -
           - go

     

       93
       93
       -
         # custom registry

     

       94
       94
       -
         git+https://tangled.org/@example.com/my_pkg:

     

       95
       95
       -
           - my_pkg

     

       96
       96
       -
       ```

     

       97
       97
       -
       

     

       98
       98
       -
       Now these dependencies are available to use in your workflow!

     

       99
       99
       -
       

     

       100
       100
       -
       ## Environment

     

       101
       101
       -
       

     

       102
       102
       -
       The `environment` field allows you define environment variables that will be available throughout the entire workflow. **Do not put secrets here, these environment variables are visible to anyone viewing the repository. You can add secrets for pipelines in your repository's settings.**

     

       103
       103
       -
       

     

       104
       104
       -
       Example:

     

       105
       105
       -
       

     

       106
       106
       -
       ```yaml

     

       107
       107
       -
       environment:

     

       108
       108
       -
         GOOS: "linux"

     

       109
       109
       -
         GOARCH: "arm64"

     

       110
       110
       -
         NODE_ENV: "production"

     

       111
       111
       -
         MY_ENV_VAR: "MY_ENV_VALUE"

     

       112
       112
       -
       ```

     

       113
       113
       -
       

     

       114
       114
       -
       ## Steps

     

       115
       115
       -
       

     

       116
       116
       -
       The `steps` field allows you to define what steps should run in the workflow. It's a list of step objects, each with the following fields:

     

       117
       117
       -
       

     

       118
       118
       -
       - `name`: This field allows you to give your step a name. This name is visible in your workflow runs, and is used to describe what the step is doing.

     

       119
       119
       -
       - `command`: This field allows you to define a command to run in that step. The step is run in a Bash shell, and the logs from the command will be visible in the pipelines page on the Tangled website. The [dependencies](#dependencies) you added will be available to use here.

     

       120
       120
       -
       - `environment`: Similar to the global [environment](#environment) config, this **optional** field is a key-value map that allows you to set environment variables for the step. **Do not put secrets here, these environment variables are visible to anyone viewing the repository. You can add secrets for pipelines in your repository's settings.**

     

       121
       121
       -
       

     

       122
       122
       -
       Example:

     

       123
       123
       -
       

     

       124
       124
       -
       ```yaml

     

       125
       125
       -
       steps:

     

       126
       126
       -
         - name: "Build backend"

     

       127
       127
       -
           command: "go build"

     

       128
       128
       -
           environment:

     

       129
       129
       -
             GOOS: "darwin"

     

       130
       130
       -
             GOARCH: "arm64"

     

       131
       131
       -
         - name: "Build frontend"

     

       132
       132
       -
           command: "npm run build"

     

       133
       133
       -
           environment:

     

       134
       134
       -
             NODE_ENV: "production"

     

       135
       135
       -
       ```

     

       136
       136
       -
       

     

       137
       137
       -
       ## Complete workflow

     

       138
       138
       -
       

     

       139
       139
       -
       ```yaml

     

       140
       140
       -
       # .tangled/workflows/build.yml

     

       141
       141
       -
       

     

       142
       142
       -
       when:

     

       143
       143
       -
         - event: ["push", "manual"]

     

       144
       144
       -
           branch: ["main", "develop"]

     

       145
       145
       -
         - event: ["pull_request"]

     

       146
       146
       -
           branch: ["main"]

     

       147
       147
       -
       

     

       148
       148
       -
       engine: "nixery"

     

       149
       149
       -
       

     

       150
       150
       -
       # using the default values

     

       151
       151
       -
       clone:

     

       152
       152
       -
         skip: false

     

       153
       153
       -
         depth: 1

     

       154
       154
       -
         submodules: false

     

       155
       155
       -
       

     

       156
       156
       -
       dependencies:

     

       157
       157
       -
         # nixpkgs

     

       158
       158
       -
         nixpkgs:

     

       159
       159
       -
           - nodejs

     

       160
       160
       -
           - go

     

       161
       161
       -
         # custom registry

     

       162
       162
       -
         git+https://tangled.org/@example.com/my_pkg:

     

       163
       163
       -
           - my_pkg

     

       164
       164
       -
       

     

       165
       165
       -
       environment:

     

       166
       166
       -
         GOOS: "linux"

     

       167
       167
       -
         GOARCH: "arm64"

     

       168
       168
       -
         NODE_ENV: "production"

     

       169
       169
       -
         MY_ENV_VAR: "MY_ENV_VALUE"

     

       170
       170
       -
       

     

       171
       171
       -
       steps:

     

       172
       172
       -
         - name: "Build backend"

     

       173
       173
       -
           command: "go build"

     

       174
       174
       -
           environment:

     

       175
       175
       -
             GOOS: "darwin"

     

       176
       176
       -
             GOARCH: "arm64"

     

       177
       177
       -
         - name: "Build frontend"

     

       178
       178
       -
           command: "npm run build"

     

       179
       179
       -
           environment:

     

       180
       180
       -
             NODE_ENV: "production"

     

       181
       181
       -
       ```

     

       182
       182
       -
       

     

       183
       183
       -
       If you want another example of a workflow, you can look at the one [Tangled uses to build the project](https://tangled.sh/@tangled.sh/core/blob/master/.tangled/workflows/build.yml).

+101

docs/styles.css

···

       1
       1
       +
       svg {

     

       2
       2
       +
         width: 16px;

     

       3
       3
       +
         height: 16px;

     

       4
       4
       +
       }

     

       5
       5
       +
       

     

       6
       6
       +
       :root {

     

       7
       7
       +
         --syntax-alert: #d20f39;

     

       8
       8
       +
         --syntax-annotation: #fe640b;

     

       9
       9
       +
         --syntax-attribute: #df8e1d;

     

       10
       10
       +
         --syntax-basen: #40a02b;

     

       11
       11
       +
         --syntax-builtin: #1e66f5;

     

       12
       12
       +
         --syntax-controlflow: #8839ef;

     

       13
       13
       +
         --syntax-char: #04a5e5;

     

       14
       14
       +
         --syntax-constant: #fe640b;

     

       15
       15
       +
         --syntax-comment: #9ca0b0;

     

       16
       16
       +
         --syntax-commentvar: #7c7f93;

     

       17
       17
       +
         --syntax-documentation: #9ca0b0;

     

       18
       18
       +
         --syntax-datatype: #df8e1d;

     

       19
       19
       +
         --syntax-decval: #40a02b;

     

       20
       20
       +
         --syntax-error: #d20f39;

     

       21
       21
       +
         --syntax-extension: #4c4f69;

     

       22
       22
       +
         --syntax-float: #40a02b;

     

       23
       23
       +
         --syntax-function: #1e66f5;

     

       24
       24
       +
         --syntax-import: #40a02b;

     

       25
       25
       +
         --syntax-information: #04a5e5;

     

       26
       26
       +
         --syntax-keyword: #8839ef;

     

       27
       27
       +
         --syntax-operator: #179299;

     

       28
       28
       +
         --syntax-other: #8839ef;

     

       29
       29
       +
         --syntax-preprocessor: #ea76cb;

     

       30
       30
       +
         --syntax-specialchar: #04a5e5;

     

       31
       31
       +
         --syntax-specialstring: #ea76cb;

     

       32
       32
       +
         --syntax-string: #40a02b;

     

       33
       33
       +
         --syntax-variable: #8839ef;

     

       34
       34
       +
         --syntax-verbatimstring: #40a02b;

     

       35
       35
       +
         --syntax-warning: #df8e1d;

     

       36
       36
       +
       }

     

       37
       37
       +
       

     

       38
       38
       +
       @media (prefers-color-scheme: dark) {

     

       39
       39
       +
         :root {

     

       40
       40
       +
           --syntax-alert: #f38ba8;

     

       41
       41
       +
           --syntax-annotation: #fab387;

     

       42
       42
       +
           --syntax-attribute: #f9e2af;

     

       43
       43
       +
           --syntax-basen: #a6e3a1;

     

       44
       44
       +
           --syntax-builtin: #89b4fa;

     

       45
       45
       +
           --syntax-controlflow: #cba6f7;

     

       46
       46
       +
           --syntax-char: #89dceb;

     

       47
       47
       +
           --syntax-constant: #fab387;

     

       48
       48
       +
           --syntax-comment: #6c7086;

     

       49
       49
       +
           --syntax-commentvar: #585b70;

     

       50
       50
       +
           --syntax-documentation: #6c7086;

     

       51
       51
       +
           --syntax-datatype: #f9e2af;

     

       52
       52
       +
           --syntax-decval: #a6e3a1;

     

       53
       53
       +
           --syntax-error: #f38ba8;

     

       54
       54
       +
           --syntax-extension: #cdd6f4;

     

       55
       55
       +
           --syntax-float: #a6e3a1;

     

       56
       56
       +
           --syntax-function: #89b4fa;

     

       57
       57
       +
           --syntax-import: #a6e3a1;

     

       58
       58
       +
           --syntax-information: #89dceb;

     

       59
       59
       +
           --syntax-keyword: #cba6f7;

     

       60
       60
       +
           --syntax-operator: #94e2d5;

     

       61
       61
       +
           --syntax-other: #cba6f7;

     

       62
       62
       +
           --syntax-preprocessor: #f5c2e7;

     

       63
       63
       +
           --syntax-specialchar: #89dceb;

     

       64
       64
       +
           --syntax-specialstring: #f5c2e7;

     

       65
       65
       +
           --syntax-string: #a6e3a1;

     

       66
       66
       +
           --syntax-variable: #cba6f7;

     

       67
       67
       +
           --syntax-verbatimstring: #a6e3a1;

     

       68
       68
       +
           --syntax-warning: #f9e2af;

     

       69
       69
       +
         }

     

       70
       70
       +
       }

     

       71
       71
       +
       

     

       72
       72
       +
       /* pandoc syntax highlighting classes */

     

       73
       73
       +
       code span.al { color: var(--syntax-alert); font-weight: bold; }                           /* alert          */

     

       74
       74
       +
       code span.an { color: var(--syntax-annotation); font-weight: bold; font-style: italic; }  /* annotation     */

     

       75
       75
       +
       code span.at { color: var(--syntax-attribute); }                                          /* attribute      */

     

       76
       76
       +
       code span.bn { color: var(--syntax-basen); }                                              /* basen          */

     

       77
       77
       +
       code span.bu { color: var(--syntax-builtin); }                                            /* builtin        */

     

       78
       78
       +
       code span.cf { color: var(--syntax-controlflow); font-weight: bold; }                     /* controlflow    */

     

       79
       79
       +
       code span.ch { color: var(--syntax-char); }                                               /* char           */

     

       80
       80
       +
       code span.cn { color: var(--syntax-constant); }                                           /* constant       */

     

       81
       81
       +
       code span.co { color: var(--syntax-comment); font-style: italic; }                        /* comment        */

     

       82
       82
       +
       code span.cv { color: var(--syntax-commentvar); font-weight: bold; font-style: italic; }  /* commentvar     */

     

       83
       83
       +
       code span.do { color: var(--syntax-documentation); font-style: italic; }                  /* documentation  */

     

       84
       84
       +
       code span.dt { color: var(--syntax-datatype); }                                           /* datatype       */

     

       85
       85
       +
       code span.dv { color: var(--syntax-decval); }                                             /* decval         */

     

       86
       86
       +
       code span.er { color: var(--syntax-error); font-weight: bold; }                           /* error          */

     

       87
       87
       +
       code span.ex { color: var(--syntax-extension); }                                          /* extension      */

     

       88
       88
       +
       code span.fl { color: var(--syntax-float); }                                              /* float          */

     

       89
       89
       +
       code span.fu { color: var(--syntax-function); }                                           /* function       */

     

       90
       90
       +
       code span.im { color: var(--syntax-import); font-weight: bold; }                          /* import         */

     

       91
       91
       +
       code span.in { color: var(--syntax-information); font-weight: bold; font-style: italic; } /* information    */

     

       92
       92
       +
       code span.kw { color: var(--syntax-keyword); font-weight: bold; }                         /* keyword        */

     

       93
       93
       +
       code span.op { color: var(--syntax-operator); }                                           /* operator       */

     

       94
       94
       +
       code span.ot { color: var(--syntax-other); }                                              /* other          */

     

       95
       95
       +
       code span.pp { color: var(--syntax-preprocessor); }                                       /* preprocessor   */

     

       96
       96
       +
       code span.sc { color: var(--syntax-specialchar); }                                        /* specialchar    */

     

       97
       97
       +
       code span.ss { color: var(--syntax-specialstring); }                                      /* specialstring  */

     

       98
       98
       +
       code span.st { color: var(--syntax-string); }                                             /* string         */

     

       99
       99
       +
       code span.va { color: var(--syntax-variable); }                                           /* variable       */

     

       100
       100
       +
       code span.vs { color: var(--syntax-verbatimstring); }                                     /* verbatimstring */

     

       101
       101
       +
       code span.wa { color: var(--syntax-warning); font-weight: bold; font-style: italic; }     /* warning        */

+117

docs/template.html

···

       1
       1
       +
       <!DOCTYPE html>

     

       2
       2
       +
       <html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$>

     

       3
       3
       +
         <head>

     

       4
       4
       +
           <meta charset="utf-8" />

     

       5
       5
       +
           <meta name="generator" content="pandoc" />

     

       6
       6
       +
           <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />

     

       7
       7
       +
           $for(author-meta)$

     

       8
       8
       +
             <meta name="author" content="$author-meta$" />

     

       9
       9
       +
           $endfor$

     

       10
       10
       +
       

     

       11
       11
       +
           $if(date-meta)$

     

       12
       12
       +
             <meta name="dcterms.date" content="$date-meta$" />

     

       13
       13
       +
           $endif$

     

       14
       14
       +
       

     

       15
       15
       +
           $if(keywords)$

     

       16
       16
       +
             <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />

     

       17
       17
       +
           $endif$

     

       18
       18
       +
       

     

       19
       19
       +
           $if(description-meta)$

     

       20
       20
       +
             <meta name="description" content="$description-meta$" />

     

       21
       21
       +
           $endif$

     

       22
       22
       +
       

     

       23
       23
       +
           <title>$pagetitle$</title>

     

       24
       24
       +
       

     

       25
       25
       +
           <style>

     

       26
       26
       +
             $styles.css()$

     

       27
       27
       +
           </style>

     

       28
       28
       +
       

     

       29
       29
       +
           $for(css)$

     

       30
       30
       +
             <link rel="stylesheet" href="$css$" />

     

       31
       31
       +
           $endfor$

     

       32
       32
       +
       

     

       33
       33
       +
           $for(header-includes)$

     

       34
       34
       +
             $header-includes$

     

       35
       35
       +
           $endfor$

     

       36
       36
       +
       

     

       37
       37
       +
           <link rel="preload" href="/static/fonts/InterVariable.woff2" as="font" type="font/woff2" crossorigin />

     

       38
       38
       +
       

     

       39
       39
       +
         </head>

     

       40
       40
       +
         <body class="bg-white dark:bg-gray-900 min-h-screen flex flex-col min-h-screen">

     

       41
       41
       +
           $for(include-before)$

     

       42
       42
       +
             $include-before$

     

       43
       43
       +
           $endfor$

     

       44
       44
       +
       

     

       45
       45
       +
           $if(toc)$

     

       46
       46
       +
             <!-- mobile topbar toc -->

     

       47
       47
       +
             <details id="mobile-$idprefix$TOC" role="doc-toc" class="md:hidden bg-gray-50 dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700 z-50 space-y-4 group px-6 py-4">

     

       48
       48
       +
               <summary class="cursor-pointer list-none text-sm font-semibold select-none flex gap-2 justify-between items-center dark:text-white">

     

       49
       49
       +
                 $if(toc-title)$$toc-title$$else$Table of Contents$endif$

     

       50
       50
       +
                 <span class="group-open:hidden inline">${ menu.svg() }</span>

     

       51
       51
       +
                 <span class="hidden group-open:inline">${ x.svg() }</span>

     

       52
       52
       +
               </summary>

     

       53
       53
       +
               ${ table-of-contents:toc.html() }

     

       54
       54
       +
             </details>

     

       55
       55
       +
             <!-- desktop sidebar toc -->

     

       56
       56
       +
             <nav id="$idprefix$TOC" role="doc-toc" class="hidden md:block fixed left-0 top-0 w-80 h-screen bg-gray-50 dark:bg-gray-800 border-r border-gray-200 dark:border-gray-700 overflow-y-auto p-4 z-50">

     

       57
       57
       +
               $if(toc-title)$

     

       58
       58
       +
               <h2 id="$idprefix$toc-title" class="text-lg font-semibold mb-4 text-gray-900">$toc-title$</h2>

     

       59
       59
       +
               $endif$

     

       60
       60
       +
               ${ table-of-contents:toc.html() }

     

       61
       61
       +
             </nav>

     

       62
       62
       +
           $endif$

     

       63
       63
       +
       

     

       64
       64
       +
           <div class="$if(toc)$md:ml-80$endif$ flex-1 flex flex-col">

     

       65
       65
       +
             <main class="max-w-4xl w-full mx-auto p-6 flex-1">

     

       66
       66
       +
               $if(top)$

     

       67
       67
       +
               $-- only print title block if this is NOT the top page

     

       68
       68
       +
               $else$

     

       69
       69
       +
               $if(title)$

     

       70
       70
       +
               <header id="title-block-header" class="mb-8 pb-8 border-b border-gray-200 dark:border-gray-700">

     

       71
       71
       +
                 <h1 class="text-4xl font-bold mb-2 text-black dark:text-white">$title$</h1>

     

       72
       72
       +
                 $if(subtitle)$

     

       73
       73
       +
                 <p class="text-xl text-gray-500 dark:text-gray-400 mb-2">$subtitle$</p>

     

       74
       74
       +
                 $endif$

     

       75
       75
       +
                 $for(author)$

     

       76
       76
       +
                 <p class="text-sm text-gray-500 dark:text-gray-400">$author$</p>

     

       77
       77
       +
                 $endfor$

     

       78
       78
       +
                 $if(date)$

     

       79
       79
       +
                 <p class="text-sm text-gray-500 dark:text-gray-400">Updated on $date$</p>

     

       80
       80
       +
                 $endif$

     

       81
       81
       +
                 $if(abstract)$

     

       82
       82
       +
                 <div class="mt-6 p-4 bg-gray-50 rounded-lg">

     

       83
       83
       +
                   <div class="text-sm font-semibold text-gray-700 uppercase mb-2">$abstract-title$</div>

     

       84
       84
       +
                   <div class="text-gray-700">$abstract$</div>

     

       85
       85
       +
                 </div>

     

       86
       86
       +
                 $endif$

     

       87
       87
       +
                 $endif$

     

       88
       88
       +
               </header>

     

       89
       89
       +
               $endif$

     

       90
       90
       +
               <article class="prose dark:prose-invert max-w-none">

     

       91
       91
       +
                 $body$

     

       92
       92
       +
               </article>

     

       93
       93
       +
             </main>

     

       94
       94
       +
             <nav id="sitenav" class="border-t border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-800 ">

     

       95
       95
       +
               <div class="max-w-4xl mx-auto px-8 py-4">

     

       96
       96
       +
                 <div class="flex justify-between gap-4">

     

       97
       97
       +
                   <span class="flex-1">

     

       98
       98
       +
                     $if(previous.url)$

     

       99
       99
       +
                     <span class="text-xs text-gray-500 dark:text-gray-400 uppercase block mb-1">Previous</span>

     

       100
       100
       +
                     <a href="$previous.url$" accesskey="p" rel="previous">$previous.title$</a>

     

       101
       101
       +
                     $endif$

     

       102
       102
       +
                   </span>

     

       103
       103
       +
                   <span class="flex-1 text-right">

     

       104
       104
       +
                     $if(next.url)$

     

       105
       105
       +
                     <span class="text-xs text-gray-500 dark:text-gray-400 uppercase block mb-1">Next</span>

     

       106
       106
       +
                     <a href="$next.url$" accesskey="n" rel="next">$next.title$</a>

     

       107
       107
       +
                     $endif$

     

       108
       108
       +
                   </span>

     

       109
       109
       +
                 </div>

     

       110
       110
       +
               </div>

     

       111
       111
       +
             </nav>

     

       112
       112
       +
           </div>

     

       113
       113
       +
           $for(include-after)$

     

       114
       114
       +
           $include-after$

     

       115
       115
       +
           $endfor$

     

       116
       116
       +
         </body>

     

       117
       117
       +
       </html>

docs/toc.html

···

       1
       1
       +
       <div class="[&_ul]:space-y-6 [&_ul]:pl-0 [&_ul]:font-bold [&_ul_ul]:pl-4 [&_ul_ul]:font-normal [&_ul_ul]:space-y-2 [&_li]:space-y-2">

     

       2
       2
       +
         $table-of-contents$

     

       3
       3
       +
       </div>

     

       4
       4
       +

+9 -9

flake.lock

···

       35
       35
        
               "systems": "systems"

     

       36
       36
        
             },

     

       37
       37
        
             "locked": {

     

       38
       38
       -
               "lastModified": 1694529238,

     

       39
       39
       -
               "narHash": "sha256-zsNZZGTGnMOf9YpHKJqMSsa0dXbfmxeoJ7xHlrt+xmY=",

     

       38
       38
       +
               "lastModified": 1731533236,

     

       39
       39
       +
               "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",

     

       40
       40
        
               "owner": "numtide",

     

       41
       41
        
               "repo": "flake-utils",

     

       42
       42
       -
               "rev": "ff7b65b44d01cf9ba6a71320833626af21126384",

     

       42
       42
       +
               "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",

     

       43
       43
        
               "type": "github"

     

       44
       44
        
             },

     

       45
       45
        
             "original": {

     
···

       56
       56
        
               ]

     

       57
       57
        
             },

     

       58
       58
        
             "locked": {

     

       59
       59
       -
               "lastModified": 1754078208,

     

       60
       60
       -
               "narHash": "sha256-YVoIFDCDpYuU3riaDEJ3xiGdPOtsx4sR5eTzHTytPV8=",

     

       59
       59
       +
               "lastModified": 1763982521,

     

       60
       60
       +
               "narHash": "sha256-ur4QIAHwgFc0vXiaxn5No/FuZicxBr2p0gmT54xZkUQ=",

     

       61
       61
        
               "owner": "nix-community",

     

       62
       62
        
               "repo": "gomod2nix",

     

       63
       63
       -
               "rev": "7f963246a71626c7fc70b431a315c4388a0c95cf",

     

       63
       63
       +
               "rev": "02e63a239d6eabd595db56852535992c898eba72",

     

       64
       64
        
               "type": "github"

     

       65
       65
        
             },

     

       66
       66
        
             "original": {

     
···

       150
       150
        
           },

     

       151
       151
        
           "nixpkgs": {

     

       152
       152
        
             "locked": {

     

       153
       153
       -
               "lastModified": 1765186076,

     

       154
       154
       -
               "narHash": "sha256-hM20uyap1a0M9d344I692r+ik4gTMyj60cQWO+hAYP8=",

     

       153
       153
       +
               "lastModified": 1766070988,

     

       154
       154
       +
               "narHash": "sha256-G/WVghka6c4bAzMhTwT2vjLccg/awmHkdKSd2JrycLc=",

     

       155
       155
        
               "owner": "nixos",

     

       156
       156
        
               "repo": "nixpkgs",

     

       157
       157
       -
               "rev": "addf7cf5f383a3101ecfba091b98d0a1263dc9b8",

     

       157
       157
       +
               "rev": "c6245e83d836d0433170a16eb185cefe0572f8b8",

     

       158
       158
        
               "type": "github"

     

       159
       159
        
             },

     

       160
       160
        
             "original": {

+5 -2

flake.nix

···

       88
       88
        
                 inherit htmx-src htmx-ws-src lucide-src inter-fonts-src ibm-plex-mono-src actor-typeahead-src;

     

       89
       89
        
               };

     

       90
       90
        
               appview = self.callPackage ./nix/pkgs/appview.nix {};

     

       91
       91
       +
               docs = self.callPackage ./nix/pkgs/docs.nix {

     

       92
       92
       +
                 inherit inter-fonts-src ibm-plex-mono-src lucide-src;

     

       93
       93
       +
               };

     

       91
       94
        
               spindle = self.callPackage ./nix/pkgs/spindle.nix {};

     

       92
       95
        
               knot-unwrapped = self.callPackage ./nix/pkgs/knot-unwrapped.nix {};

     

       93
       96
        
               knot = self.callPackage ./nix/pkgs/knot.nix {};

     

       94
       97
        
             });

     

       95
       98
        
         in {

     

       96
       99
        
           overlays.default = final: prev: {

     

       97
       97
       -
             inherit (mkPackageSet final) lexgen goat sqlite-lib spindle knot-unwrapped knot appview;

     

       100
       100
       +
             inherit (mkPackageSet final) lexgen goat sqlite-lib spindle knot-unwrapped knot appview docs;

     

       98
       101
        
           };

     

       99
       102
        
       

     

       100
       103
        
           packages = forAllSystems (system: let

     
···

       103
       106
        
             staticPackages = mkPackageSet pkgs.pkgsStatic;

     

       104
       107
        
             crossPackages = mkPackageSet pkgs.pkgsCross.gnu64.pkgsStatic;

     

       105
       108
        
           in {

     

       106
       106
       -
             inherit (packages) appview appview-static-files lexgen goat spindle knot knot-unwrapped sqlite-lib;

     

       109
       109
       +
             inherit (packages) appview appview-static-files lexgen goat spindle knot knot-unwrapped sqlite-lib docs;

     

       107
       110
        
       

     

       108
       111
        
             pkgsStatic-appview = staticPackages.appview;

     

       109
       112
        
             pkgsStatic-knot = staticPackages.knot;

+2 -1

go.mod

···

       45
       45
        
       	github.com/urfave/cli/v3 v3.3.3

     

       46
       46
        
       	github.com/whyrusleeping/cbor-gen v0.3.1

     

       47
       47
        
       	github.com/yuin/goldmark v1.7.13

     

       48
       48
       +
       	github.com/yuin/goldmark-emoji v1.0.6

     

       48
       49
        
       	github.com/yuin/goldmark-highlighting/v2 v2.0.0-20230729083705-37449abec8cc

     

       49
       50
        
       	gitlab.com/staticnoise/goldmark-callout v0.0.0-20240609120641-6366b799e4ab

     

       50
       51
        
       	golang.org/x/crypto v0.40.0

     

       51
       52
        
       	golang.org/x/exp v0.0.0-20250620022241-b7579e27df2b

     

       52
       53
        
       	golang.org/x/image v0.31.0

     

       53
       54
        
       	golang.org/x/net v0.42.0

     

       54
       54
       -
       	golang.org/x/sync v0.17.0

     

       55
       55
        
       	golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da

     

       56
       56
        
       	gopkg.in/yaml.v3 v3.0.1

     

       57
       57
        
       )

     
···

       203
       203
        
       	go.uber.org/atomic v1.11.0 // indirect

     

       204
       204
        
       	go.uber.org/multierr v1.11.0 // indirect

     

       205
       205
        
       	go.uber.org/zap v1.27.0 // indirect

     

       206
       206
       +
       	golang.org/x/sync v0.17.0 // indirect

     

       206
       207
        
       	golang.org/x/sys v0.34.0 // indirect

     

       207
       208
        
       	golang.org/x/text v0.29.0 // indirect

     

       208
       209
        
       	golang.org/x/time v0.12.0 // indirect

go.sum

···

       505
       505
        
       github.com/yuin/goldmark v1.4.15/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=

     

       506
       506
        
       github.com/yuin/goldmark v1.7.13 h1:GPddIs617DnBLFFVJFgpo1aBfe/4xcvMc3SB5t/D0pA=

     

       507
       507
        
       github.com/yuin/goldmark v1.7.13/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=

     

       508
       508
       +
       github.com/yuin/goldmark-emoji v1.0.6 h1:QWfF2FYaXwL74tfGOW5izeiZepUDroDJfWubQI9HTHs=

     

       509
       509
       +
       github.com/yuin/goldmark-emoji v1.0.6/go.mod h1:ukxJDKFpdFb5x0a5HqbdlcKtebh086iJpI31LTKmWuA=

     

       508
       510
        
       github.com/yuin/goldmark-highlighting/v2 v2.0.0-20230729083705-37449abec8cc h1:+IAOyRda+RLrxa1WC7umKOZRsGq4QrFFMYApOeHzQwQ=

     

       509
       511
        
       github.com/yuin/goldmark-highlighting/v2 v2.0.0-20230729083705-37449abec8cc/go.mod h1:ovIvrum6DQJA4QsJSovrkC4saKHQVs7TvcaeO8AIl5I=

     

       510
       512
        
       gitlab.com/staticnoise/goldmark-callout v0.0.0-20240609120641-6366b799e4ab h1:gK9tS6QJw5F0SIhYJnGG2P83kuabOdmWBbSmZhJkz2A=

+4 -4

hook/hook.go

···

       48
       48
        
       		},

     

       49
       49
        
       		Commands: []*cli.Command{

     

       50
       50
        
       			{

     

       51
       51
       -
       				Name:   "post-recieve",

     

       52
       52
       -
       				Usage:  "sends a post-recieve hook to the knot (waits for stdin)",

     

       53
       53
       -
       				Action: postRecieve,

     

       51
       51
       +
       				Name:   "post-receive",

     

       52
       52
       +
       				Usage:  "sends a post-receive hook to the knot (waits for stdin)",

     

       53
       53
       +
       				Action: postReceive,

     

       54
       54
        
       			},

     

       55
       55
        
       		},

     

       56
       56
        
       	}

     

       57
       57
        
       }

     

       58
       58
        
       

     

       59
       59
       -
       func postRecieve(ctx context.Context, cmd *cli.Command) error {

     

       59
       59
       +
       func postReceive(ctx context.Context, cmd *cli.Command) error {

     

       60
       60
        
       	gitDir := cmd.String("git-dir")

     

       61
       61
        
       	userDid := cmd.String("user-did")

     

       62
       62
        
       	userHandle := cmd.String("user-handle")

+1 -1

hook/setup.go

···

       138
       138
        
           option_var="GIT_PUSH_OPTION_$i"

     

       139
       139
        
           push_options+=(-push-option "${!option_var}")

     

       140
       140
        
       done

     

       141
       141
       -
       %s hook -git-dir "$GIT_DIR" -user-did "$GIT_USER_DID" -user-handle "$GIT_USER_HANDLE" -internal-api "%s" "${push_options[@]}" post-recieve

     

       141
       141
       +
       %s hook -git-dir "$GIT_DIR" -user-did "$GIT_USER_DID" -user-handle "$GIT_USER_HANDLE" -internal-api "%s" "${push_options[@]}" post-receive

     

       142
       142
        
       	`, executablePath, config.internalApi)

     

       143
       143
        
       

     

       144
       144
        
       	return os.WriteFile(hookPath, []byte(hookContent), 0755)

+1 -1

input.css

···

       162
       162
        
               }

     

       163
       163
        
       

     

       164
       164
        
               .prose a.mention {

     

       165
       165
       -
                   @apply no-underline hover:underline;

     

       165
       165
       +
                   @apply no-underline hover:underline font-bold;

     

       166
       166
        
               }

     

       167
       167
        
       

     

       168
       168
        
               .prose li {

+11 -4

knotserver/db/db.go

···

       32
       32
        
       		return nil, err

     

       33
       33
        
       	}

     

       34
       34
        
       

     

       35
       35
       -
       	// NOTE: If any other migration is added here, you MUST

     

       36
       36
       -
       	// copy the pattern in appview: use a single sql.Conn

     

       37
       37
       -
       	// for every migration.

     

       35
       35
       +
       	conn, err := db.Conn(ctx)

     

       36
       36
       +
       	if err != nil {

     

       37
       37
       +
       		return nil, err

     

       38
       38
       +
       	}

     

       39
       39
       +
       	defer conn.Close()

     

       38
       40
        
       

     

       39
       39
       -
       	_, err = db.Exec(`

     

       41
       41
       +
       	_, err = conn.ExecContext(ctx, `

     

       40
       42
        
       		create table if not exists known_dids (

     

       41
       43
        
       			did text primary key

     

       42
       44
        
       		);

     
···

       61
       63
        
       			event text not null, -- json

     

       62
       64
        
       			created integer not null default (strftime('%s', 'now')),

     

       63
       65
        
       			primary key (rkey, nsid)

     

       66
       66
       +
       		);

     

       67
       67
       +
       

     

       68
       68
       +
       		create table if not exists migrations (

     

       69
       69
       +
       			id integer primary key autoincrement,

     

       70
       70
       +
       			name text unique

     

       64
       71
        
       		);

     

       65
       72
        
       	`)

     

       66
       73
        
       	if err != nil {

+13 -1

knotserver/git/service/service.go

···

       95
       95
        
       	return c.RunService(cmd)

     

       96
       96
        
       }

     

       97
       97
        
       

     

       98
       98
       +
       func (c *ServiceCommand) UploadArchive() error {

     

       99
       99
       +
       	cmd := exec.Command("git", []string{

     

       100
       100
       +
       		"upload-archive",

     

       101
       101
       +
       		".",

     

       102
       102
       +
       	}...)

     

       103
       103
       +
       

     

       104
       104
       +
       	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}

     

       105
       105
       +
       	cmd.Env = append(cmd.Env, fmt.Sprintf("GIT_PROTOCOL=%s", c.GitProtocol))

     

       106
       106
       +
       	cmd.Dir = c.Dir

     

       107
       107
       +
       

     

       108
       108
       +
       	return c.RunService(cmd)

     

       109
       109
       +
       }

     

       110
       110
       +
       

     

       98
       111
        
       func (c *ServiceCommand) UploadPack() error {

     

       99
       112
        
       	cmd := exec.Command("git", []string{

     

       100
       100
       -
       		"-c", "uploadpack.allowFilter=true",

     

       101
       113
        
       		"upload-pack",

     

       102
       114
        
       		"--stateless-rpc",

     

       103
       115
        
       		".",

+47

knotserver/git.go

···

       56
       56
        
       	}

     

       57
       57
        
       }

     

       58
       58
        
       

     

       59
       59
       +
       func (h *Knot) UploadArchive(w http.ResponseWriter, r *http.Request) {

     

       60
       60
       +
       	did := chi.URLParam(r, "did")

     

       61
       61
       +
       	name := chi.URLParam(r, "name")

     

       62
       62
       +
       	repo, err := securejoin.SecureJoin(h.c.Repo.ScanPath, filepath.Join(did, name))

     

       63
       63
       +
       	if err != nil {

     

       64
       64
       +
       		gitError(w, err.Error(), http.StatusInternalServerError)

     

       65
       65
       +
       		h.l.Error("git: failed to secure join repo path", "handler", "UploadPack", "error", err)

     

       66
       66
       +
       		return

     

       67
       67
       +
       	}

     

       68
       68
       +
       

     

       69
       69
       +
       	const expectedContentType = "application/x-git-upload-archive-request"

     

       70
       70
       +
       	contentType := r.Header.Get("Content-Type")

     

       71
       71
       +
       	if contentType != expectedContentType {

     

       72
       72
       +
       		gitError(w, fmt.Sprintf("Expected Content-Type: '%s', but received '%s'.", expectedContentType, contentType), http.StatusUnsupportedMediaType)

     

       73
       73
       +
       	}

     

       74
       74
       +
       

     

       75
       75
       +
       	var bodyReader io.ReadCloser = r.Body

     

       76
       76
       +
       	if r.Header.Get("Content-Encoding") == "gzip" {

     

       77
       77
       +
       		gzipReader, err := gzip.NewReader(r.Body)

     

       78
       78
       +
       		if err != nil {

     

       79
       79
       +
       			gitError(w, err.Error(), http.StatusInternalServerError)

     

       80
       80
       +
       			h.l.Error("git: failed to create gzip reader", "handler", "UploadArchive", "error", err)

     

       81
       81
       +
       			return

     

       82
       82
       +
       		}

     

       83
       83
       +
       		defer gzipReader.Close()

     

       84
       84
       +
       		bodyReader = gzipReader

     

       85
       85
       +
       	}

     

       86
       86
       +
       

     

       87
       87
       +
       	w.Header().Set("Content-Type", "application/x-git-upload-archive-result")

     

       88
       88
       +
       

     

       89
       89
       +
       	h.l.Info("git: executing git-upload-archive", "handler", "UploadArchive", "repo", repo)

     

       90
       90
       +
       

     

       91
       91
       +
       	cmd := service.ServiceCommand{

     

       92
       92
       +
       		GitProtocol: r.Header.Get("Git-Protocol"),

     

       93
       93
       +
       		Dir:         repo,

     

       94
       94
       +
       		Stdout:      w,

     

       95
       95
       +
       		Stdin:       bodyReader,

     

       96
       96
       +
       	}

     

       97
       97
       +
       

     

       98
       98
       +
       	w.WriteHeader(http.StatusOK)

     

       99
       99
       +
       

     

       100
       100
       +
       	if err := cmd.UploadArchive(); err != nil {

     

       101
       101
       +
       		h.l.Error("git: failed to execute git-upload-pack", "handler", "UploadPack", "error", err)

     

       102
       102
       +
       		return

     

       103
       103
       +
       	}

     

       104
       104
       +
       }

     

       105
       105
       +
       

     

       59
       106
        
       func (h *Knot) UploadPack(w http.ResponseWriter, r *http.Request) {

     

       60
       107
        
       	did := chi.URLParam(r, "did")

     

       61
       108
        
       	name := chi.URLParam(r, "name")

knotserver/router.go

···

       82
       82
        
       		r.Route("/{name}", func(r chi.Router) {

     

       83
       83
        
       			// routes for git operations

     

       84
       84
        
       			r.Get("/info/refs", h.InfoRefs)

     

       85
       85
       +
       			r.Post("/git-upload-archive", h.UploadArchive)

     

       85
       86
        
       			r.Post("/git-upload-pack", h.UploadPack)

     

       86
       87
        
       			r.Post("/git-receive-pack", h.ReceivePack)

     

       87
       88
        
       		})

+8 -2

lexicons/pulls/pull.json

···

       12
       12
        
               "required": [

     

       13
       13
        
                 "target",

     

       14
       14
        
                 "title",

     

       15
       15
       -
                 "patch",

     

       15
       15
       +
                 "patchBlob",

     

       16
       16
        
                 "createdAt"

     

       17
       17
        
               ],

     

       18
       18
        
               "properties": {

     
···

       27
       27
        
                   "type": "string"

     

       28
       28
        
                 },

     

       29
       29
        
                 "patch": {

     

       30
       30
       -
                   "type": "string"

     

       30
       30
       +
                   "type": "string",

     

       31
       31
       +
                   "description": "(deprecated) use patchBlob instead"

     

       32
       32
       +
                 },

     

       33
       33
       +
                 "patchBlob": {

     

       34
       34
       +
                   "type": "blob",

     

       35
       35
       +
                   "accept": "text/x-patch",

     

       36
       36
       +
                   "description": "patch content"

     

       31
       37
        
                 },

     

       32
       38
        
                 "source": {

     

       33
       39
        
                   "type": "ref",

nix/gomod2nix.toml

···

       530
       530
        
         [mod."github.com/yuin/goldmark"]

     

       531
       531
        
           version = "v1.7.13"

     

       532
       532
        
           hash = "sha256-vBCxZrPYPc8x/nvAAv3Au59dCCyfS80Vw3/a9EXK7TE="

     

       533
       533
       +
         [mod."github.com/yuin/goldmark-emoji"]

     

       534
       534
       +
           version = "v1.0.6"

     

       535
       535
       +
           hash = "sha256-+d6bZzOPE+JSFsZbQNZMCWE+n3jgcQnkPETVk47mxSY="

     

       533
       536
        
         [mod."github.com/yuin/goldmark-highlighting/v2"]

     

       534
       537
        
           version = "v2.0.0-20230729083705-37449abec8cc"

     

       535
       538
        
           hash = "sha256-HpiwU7jIeDUAg2zOpTIiviQir8dpRPuXYh2nqFFccpg="

+41

nix/pkgs/docs.nix

···

       1
       1
       +
       {

     

       2
       2
       +
         pandoc,

     

       3
       3
       +
         tailwindcss,

     

       4
       4
       +
         runCommandLocal,

     

       5
       5
       +
         inter-fonts-src,

     

       6
       6
       +
         ibm-plex-mono-src,

     

       7
       7
       +
         lucide-src,

     

       8
       8
       +
         src,

     

       9
       9
       +
       }:

     

       10
       10
       +
       runCommandLocal "docs" {} ''

     

       11
       11
       +
         mkdir -p working

     

       12
       12
       +
       

     

       13
       13
       +
         # copy templates, themes, styles, filters to working directory

     

       14
       14
       +
         cp ${src}/docs/*.html working/

     

       15
       15
       +
         cp ${src}/docs/*.theme working/

     

       16
       16
       +
         cp ${src}/docs/*.css working/

     

       17
       17
       +
       

     

       18
       18
       +
         # icons

     

       19
       19
       +
         cp -rf ${lucide-src}/*.svg working/

     

       20
       20
       +
       

     

       21
       21
       +
         # content

     

       22
       22
       +
         ${pandoc}/bin/pandoc ${src}/docs/DOCS.md \

     

       23
       23
       +
           -o $out/ \

     

       24
       24
       +
           -t chunkedhtml \

     

       25
       25
       +
           --variable toc \

     

       26
       26
       +
           --toc-depth=2 \

     

       27
       27
       +
           --css=stylesheet.css \

     

       28
       28
       +
           --chunk-template="%i.html" \

     

       29
       29
       +
           --highlight-style=working/highlight.theme \

     

       30
       30
       +
           --template=working/template.html

     

       31
       31
       +
       

     

       32
       32
       +
         # fonts

     

       33
       33
       +
         mkdir -p $out/static/fonts

     

       34
       34
       +
         cp -f ${inter-fonts-src}/web/InterVariable*.woff2 $out/static/fonts/

     

       35
       35
       +
         cp -f ${inter-fonts-src}/web/InterDisplay*.woff2 $out/static/fonts/

     

       36
       36
       +
         cp -f ${inter-fonts-src}/InterVariable*.ttf $out/static/fonts/

     

       37
       37
       +
         cp -f ${ibm-plex-mono-src}/fonts/complete/woff2/IBMPlexMono*.woff2 $out/static/fonts/

     

       38
       38
       +
       

     

       39
       39
       +
         # styles

     

       40
       40
       +
         cd ${src} && ${tailwindcss}/bin/tailwindcss -i input.css -o $out/stylesheet.css

     

       41
       41
       +
       ''

+1 -1

nix/vm.nix

···

       8
       8
        
           var = builtins.getEnv name;

     

       9
       9
        
         in

     

       10
       10
        
           if var == ""

     

       11
       11
       -
           then throw "\$${name} must be defined, see docs/hacking.md for more details"

     

       11
       11
       +
           then throw "\$${name} must be defined, see https://docs.tangled.org/hacking-on-tangled.html#hacking-on-tangled for more details"

     

       12
       12
        
           else var;

     

       13
       13
        
         envVarOr = name: default: let

     

       14
       14
        
           var = builtins.getEnv name;

+3 -3

readme.md

···

       10
       10
        
       

     

       11
       11
        
       ## docs

     

       12
       12
        
       

     

       13
       13
       -
       * [knot hosting guide](/docs/knot-hosting.md)

     

       14
       14
       -
       * [contributing guide](/docs/contributing.md) **please read before opening a PR!**

     

       15
       15
       -
       * [hacking on tangled](/docs/hacking.md)

     

       13
       13
       +
       - [knot hosting guide](https://docs.tangled.org/knot-self-hosting-guide.html#knot-self-hosting-guide)

     

       14
       14
       +
       - [contributing guide](https://docs.tangled.org/contribution-guide.html#contribution-guide) **please read before opening a PR!**

     

       15
       15
       +
       - [hacking on tangled](https://docs.tangled.org/hacking-on-tangled.html#hacking-on-tangled)

     

       16
       16
        
       

     

       17
       17
        
       ## security

     

       18
       18

spindle/db/repos.go

···

       16
       16
        
       	if err != nil {

     

       17
       17
        
       		return nil, err

     

       18
       18
        
       	}

     

       19
       19
       +
       	defer rows.Close()

     

       19
       20
        
       

     

       20
       21
        
       	var knots []string

     

       21
       22
        
       	for rows.Next() {

+22 -21

spindle/engine/engine.go

···

       3
       3
        
       import (

     

       4
       4
        
       	"context"

     

       5
       5
        
       	"errors"

     

       6
       6
       -
       	"fmt"

     

       7
       6
        
       	"log/slog"

     

       7
       7
       +
       	"sync"

     

       8
       8
        
       

     

       9
       9
        
       	securejoin "github.com/cyphar/filepath-securejoin"

     

       10
       10
       -
       	"golang.org/x/sync/errgroup"

     

       11
       10
        
       	"tangled.org/core/notifier"

     

       12
       11
        
       	"tangled.org/core/spindle/config"

     

       13
       12
        
       	"tangled.org/core/spindle/db"

     
···

       31
       30
        
       		}

     

       32
       31
        
       	}

     

       33
       32
        
       

     

       34
       34
       -
       	eg, ctx := errgroup.WithContext(ctx)

     

       33
       33
       +
       	var wg sync.WaitGroup

     

       35
       34
        
       	for eng, wfs := range pipeline.Workflows {

     

       36
       35
        
       		workflowTimeout := eng.WorkflowTimeout()

     

       37
       36
        
       		l.Info("using workflow timeout", "timeout", workflowTimeout)

     

       38
       37
        
       

     

       39
       38
        
       		for _, w := range wfs {

     

       40
       40
       -
       			eg.Go(func() error {

     

       39
       39
       +
       			wg.Add(1)

     

       40
       40
       +
       			go func() {

     

       41
       41
       +
       				defer wg.Done()

     

       42
       42
       +
       

     

       41
       43
        
       				wid := models.WorkflowId{

     

       42
       44
        
       					PipelineId: pipelineId,

     

       43
       45
        
       					Name:       w.Name,

     
···

       45
       47
        
       

     

       46
       48
        
       				err := db.StatusRunning(wid, n)

     

       47
       49
        
       				if err != nil {

     

       48
       48
       -
       					return err

     

       50
       50
       +
       					l.Error("failed to set workflow status to running", "wid", wid, "err", err)

     

       51
       51
       +
       					return

     

       49
       52
        
       				}

     

       50
       53
        
       

     

       51
       54
        
       				err = eng.SetupWorkflow(ctx, wid, &w)

     
···

       61
       64
        
       

     

       62
       65
        
       					dbErr := db.StatusFailed(wid, err.Error(), -1, n)

     

       63
       66
        
       					if dbErr != nil {

     

       64
       64
       -
       						return dbErr

     

       67
       67
       +
       						l.Error("failed to set workflow status to failed", "wid", wid, "err", dbErr)

     

       65
       68
        
       					}

     

       66
       66
       -
       					return err

     

       69
       69
       +
       					return

     

       67
       70
        
       				}

     

       68
       71
        
       				defer eng.DestroyWorkflow(ctx, wid)

     

       69
       72
        
       

     

       70
       70
       -
       				wfLogger, err := models.NewWorkflowLogger(cfg.Server.LogDir, wid)

     

       73
       73
       +
       				secretValues := make([]string, len(allSecrets))

     

       74
       74
       +
       				for i, s := range allSecrets {

     

       75
       75
       +
       					secretValues[i] = s.Value

     

       76
       76
       +
       				}

     

       77
       77
       +
       				wfLogger, err := models.NewWorkflowLogger(cfg.Server.LogDir, wid, secretValues)

     

       71
       78
        
       				if err != nil {

     

       72
       79
        
       					l.Warn("failed to setup step logger; logs will not be persisted", "error", err)

     

       73
       80
        
       					wfLogger = nil

     
···

       99
       106
        
       						if errors.Is(err, ErrTimedOut) {

     

       100
       107
        
       							dbErr := db.StatusTimeout(wid, n)

     

       101
       108
        
       							if dbErr != nil {

     

       102
       102
       -
       								return dbErr

     

       109
       109
       +
       								l.Error("failed to set workflow status to timeout", "wid", wid, "err", dbErr)

     

       103
       110
        
       							}

     

       104
       111
        
       						} else {

     

       105
       112
        
       							dbErr := db.StatusFailed(wid, err.Error(), -1, n)

     

       106
       113
        
       							if dbErr != nil {

     

       107
       107
       -
       								return dbErr

     

       114
       114
       +
       								l.Error("failed to set workflow status to failed", "wid", wid, "err", dbErr)

     

       108
       115
        
       							}

     

       109
       116
        
       						}

     

       110
       110
       -
       

     

       111
       111
       -
       						return fmt.Errorf("starting steps image: %w", err)

     

       117
       117
       +
       						return

     

       112
       118
        
       					}

     

       113
       119
        
       				}

     

       114
       120
        
       

     

       115
       121
        
       				err = db.StatusSuccess(wid, n)

     

       116
       122
        
       				if err != nil {

     

       117
       117
       -
       					return err

     

       123
       123
       +
       					l.Error("failed to set workflow status to success", "wid", wid, "err", err)

     

       118
       124
        
       				}

     

       119
       119
       -
       

     

       120
       120
       -
       				return nil

     

       121
       121
       -
       			})

     

       125
       125
       +
       			}()

     

       122
       126
        
       		}

     

       123
       127
        
       	}

     

       124
       128
        
       

     

       125
       125
       -
       	if err := eg.Wait(); err != nil {

     

       126
       126
       -
       		l.Error("failed to run one or more workflows", "err", err)

     

       127
       127
       -
       	} else {

     

       128
       128
       -
       		l.Info("successfully ran full pipeline")

     

       129
       129
       -
       	}

     

       129
       129
       +
       	wg.Wait()

     

       130
       130
       +
       	l.Info("all workflows completed")

     

       130
       131
        
       }

+6 -1

spindle/models/logger.go

···

       12
       12
        
       type WorkflowLogger struct {

     

       13
       13
        
       	file    *os.File

     

       14
       14
        
       	encoder *json.Encoder

     

       15
       15
       +
       	mask    *SecretMask

     

       15
       16
        
       }

     

       16
       17
        
       

     

       17
       17
       -
       func NewWorkflowLogger(baseDir string, wid WorkflowId) (*WorkflowLogger, error) {

     

       18
       18
       +
       func NewWorkflowLogger(baseDir string, wid WorkflowId, secretValues []string) (*WorkflowLogger, error) {

     

       18
       19
        
       	path := LogFilePath(baseDir, wid)

     

       19
       20
        
       

     

       20
       21
        
       	file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)

     
···

       25
       26
        
       	return &WorkflowLogger{

     

       26
       27
        
       		file:    file,

     

       27
       28
        
       		encoder: json.NewEncoder(file),

     

       29
       29
       +
       		mask:    NewSecretMask(secretValues),

     

       28
       30
        
       	}, nil

     

       29
       31
        
       }

     

       30
       32
        
       

     
···

       62
       64
        
       

     

       63
       65
        
       func (w *dataWriter) Write(p []byte) (int, error) {

     

       64
       66
        
       	line := strings.TrimRight(string(p), "\r\n")

     

       67
       67
       +
       	if w.logger.mask != nil {

     

       68
       68
       +
       		line = w.logger.mask.Mask(line)

     

       69
       69
       +
       	}

     

       65
       70
        
       	entry := NewDataLogLine(w.idx, line, w.stream)

     

       66
       71
        
       	if err := w.logger.encoder.Encode(entry); err != nil {

     

       67
       72
        
       		return 0, err

+51

spindle/models/secret_mask.go

···

       1
       1
       +
       package models

     

       2
       2
       +
       

     

       3
       3
       +
       import (

     

       4
       4
       +
       	"encoding/base64"

     

       5
       5
       +
       	"strings"

     

       6
       6
       +
       )

     

       7
       7
       +
       

     

       8
       8
       +
       // SecretMask replaces secret values in strings with "***".

     

       9
       9
       +
       type SecretMask struct {

     

       10
       10
       +
       	replacer *strings.Replacer

     

       11
       11
       +
       }

     

       12
       12
       +
       

     

       13
       13
       +
       // NewSecretMask creates a mask for the given secret values.

     

       14
       14
       +
       // Also registers base64-encoded variants of each secret.

     

       15
       15
       +
       func NewSecretMask(values []string) *SecretMask {

     

       16
       16
       +
       	var pairs []string

     

       17
       17
       +
       

     

       18
       18
       +
       	for _, value := range values {

     

       19
       19
       +
       		if value == "" {

     

       20
       20
       +
       			continue

     

       21
       21
       +
       		}

     

       22
       22
       +
       

     

       23
       23
       +
       		pairs = append(pairs, value, "***")

     

       24
       24
       +
       

     

       25
       25
       +
       		b64 := base64.StdEncoding.EncodeToString([]byte(value))

     

       26
       26
       +
       		if b64 != value {

     

       27
       27
       +
       			pairs = append(pairs, b64, "***")

     

       28
       28
       +
       		}

     

       29
       29
       +
       

     

       30
       30
       +
       		b64NoPad := strings.TrimRight(b64, "=")

     

       31
       31
       +
       		if b64NoPad != b64 && b64NoPad != value {

     

       32
       32
       +
       			pairs = append(pairs, b64NoPad, "***")

     

       33
       33
       +
       		}

     

       34
       34
       +
       	}

     

       35
       35
       +
       

     

       36
       36
       +
       	if len(pairs) == 0 {

     

       37
       37
       +
       		return nil

     

       38
       38
       +
       	}

     

       39
       39
       +
       

     

       40
       40
       +
       	return &SecretMask{

     

       41
       41
       +
       		replacer: strings.NewReplacer(pairs...),

     

       42
       42
       +
       	}

     

       43
       43
       +
       }

     

       44
       44
       +
       

     

       45
       45
       +
       // Mask replaces all registered secret values with "***".

     

       46
       46
       +
       func (m *SecretMask) Mask(input string) string {

     

       47
       47
       +
       	if m == nil || m.replacer == nil {

     

       48
       48
       +
       		return input

     

       49
       49
       +
       	}

     

       50
       50
       +
       	return m.replacer.Replace(input)

     

       51
       51
       +
       }

+135

spindle/models/secret_mask_test.go

···

       1
       1
       +
       package models

     

       2
       2
       +
       

     

       3
       3
       +
       import (

     

       4
       4
       +
       	"encoding/base64"

     

       5
       5
       +
       	"testing"

     

       6
       6
       +
       )

     

       7
       7
       +
       

     

       8
       8
       +
       func TestSecretMask_BasicMasking(t *testing.T) {

     

       9
       9
       +
       	mask := NewSecretMask([]string{"mysecret123"})

     

       10
       10
       +
       

     

       11
       11
       +
       	input := "The password is mysecret123 in this log"

     

       12
       12
       +
       	expected := "The password is *** in this log"

     

       13
       13
       +
       

     

       14
       14
       +
       	result := mask.Mask(input)

     

       15
       15
       +
       	if result != expected {

     

       16
       16
       +
       		t.Errorf("expected %q, got %q", expected, result)

     

       17
       17
       +
       	}

     

       18
       18
       +
       }

     

       19
       19
       +
       

     

       20
       20
       +
       func TestSecretMask_Base64Encoded(t *testing.T) {

     

       21
       21
       +
       	secret := "mysecret123"

     

       22
       22
       +
       	mask := NewSecretMask([]string{secret})

     

       23
       23
       +
       

     

       24
       24
       +
       	b64 := base64.StdEncoding.EncodeToString([]byte(secret))

     

       25
       25
       +
       	input := "Encoded: " + b64

     

       26
       26
       +
       	expected := "Encoded: ***"

     

       27
       27
       +
       

     

       28
       28
       +
       	result := mask.Mask(input)

     

       29
       29
       +
       	if result != expected {

     

       30
       30
       +
       		t.Errorf("expected %q, got %q", expected, result)

     

       31
       31
       +
       	}

     

       32
       32
       +
       }

     

       33
       33
       +
       

     

       34
       34
       +
       func TestSecretMask_Base64NoPadding(t *testing.T) {

     

       35
       35
       +
       	// "test" encodes to "dGVzdA==" with padding

     

       36
       36
       +
       	secret := "test"

     

       37
       37
       +
       	mask := NewSecretMask([]string{secret})

     

       38
       38
       +
       

     

       39
       39
       +
       	b64NoPad := "dGVzdA" // base64 without padding

     

       40
       40
       +
       	input := "Token: " + b64NoPad

     

       41
       41
       +
       	expected := "Token: ***"

     

       42
       42
       +
       

     

       43
       43
       +
       	result := mask.Mask(input)

     

       44
       44
       +
       	if result != expected {

     

       45
       45
       +
       		t.Errorf("expected %q, got %q", expected, result)

     

       46
       46
       +
       	}

     

       47
       47
       +
       }

     

       48
       48
       +
       

     

       49
       49
       +
       func TestSecretMask_MultipleSecrets(t *testing.T) {

     

       50
       50
       +
       	mask := NewSecretMask([]string{"password1", "apikey123"})

     

       51
       51
       +
       

     

       52
       52
       +
       	input := "Using password1 and apikey123 for auth"

     

       53
       53
       +
       	expected := "Using *** and *** for auth"

     

       54
       54
       +
       

     

       55
       55
       +
       	result := mask.Mask(input)

     

       56
       56
       +
       	if result != expected {

     

       57
       57
       +
       		t.Errorf("expected %q, got %q", expected, result)

     

       58
       58
       +
       	}

     

       59
       59
       +
       }

     

       60
       60
       +
       

     

       61
       61
       +
       func TestSecretMask_MultipleOccurrences(t *testing.T) {

     

       62
       62
       +
       	mask := NewSecretMask([]string{"secret"})

     

       63
       63
       +
       

     

       64
       64
       +
       	input := "secret appears twice: secret"

     

       65
       65
       +
       	expected := "*** appears twice: ***"

     

       66
       66
       +
       

     

       67
       67
       +
       	result := mask.Mask(input)

     

       68
       68
       +
       	if result != expected {

     

       69
       69
       +
       		t.Errorf("expected %q, got %q", expected, result)

     

       70
       70
       +
       	}

     

       71
       71
       +
       }

     

       72
       72
       +
       

     

       73
       73
       +
       func TestSecretMask_ShortValues(t *testing.T) {

     

       74
       74
       +
       	mask := NewSecretMask([]string{"abc", "xy", ""})

     

       75
       75
       +
       

     

       76
       76
       +
       	if mask == nil {

     

       77
       77
       +
       		t.Fatal("expected non-nil mask")

     

       78
       78
       +
       	}

     

       79
       79
       +
       

     

       80
       80
       +
       	input := "abc xy test"

     

       81
       81
       +
       	expected := "*** *** test"

     

       82
       82
       +
       	result := mask.Mask(input)

     

       83
       83
       +
       	if result != expected {

     

       84
       84
       +
       		t.Errorf("expected %q, got %q", expected, result)

     

       85
       85
       +
       	}

     

       86
       86
       +
       }

     

       87
       87
       +
       

     

       88
       88
       +
       func TestSecretMask_NilMask(t *testing.T) {

     

       89
       89
       +
       	var mask *SecretMask

     

       90
       90
       +
       

     

       91
       91
       +
       	input := "some input text"

     

       92
       92
       +
       	result := mask.Mask(input)

     

       93
       93
       +
       	if result != input {

     

       94
       94
       +
       		t.Errorf("expected %q, got %q", input, result)

     

       95
       95
       +
       	}

     

       96
       96
       +
       }

     

       97
       97
       +
       

     

       98
       98
       +
       func TestSecretMask_EmptyInput(t *testing.T) {

     

       99
       99
       +
       	mask := NewSecretMask([]string{"secret"})

     

       100
       100
       +
       

     

       101
       101
       +
       	result := mask.Mask("")

     

       102
       102
       +
       	if result != "" {

     

       103
       103
       +
       		t.Errorf("expected empty string, got %q", result)

     

       104
       104
       +
       	}

     

       105
       105
       +
       }

     

       106
       106
       +
       

     

       107
       107
       +
       func TestSecretMask_NoMatch(t *testing.T) {

     

       108
       108
       +
       	mask := NewSecretMask([]string{"secretvalue"})

     

       109
       109
       +
       

     

       110
       110
       +
       	input := "nothing to mask here"

     

       111
       111
       +
       	result := mask.Mask(input)

     

       112
       112
       +
       	if result != input {

     

       113
       113
       +
       		t.Errorf("expected %q, got %q", input, result)

     

       114
       114
       +
       	}

     

       115
       115
       +
       }

     

       116
       116
       +
       

     

       117
       117
       +
       func TestSecretMask_EmptySecretsList(t *testing.T) {

     

       118
       118
       +
       	mask := NewSecretMask([]string{})

     

       119
       119
       +
       

     

       120
       120
       +
       	if mask != nil {

     

       121
       121
       +
       		t.Error("expected nil mask for empty secrets list")

     

       122
       122
       +
       	}

     

       123
       123
       +
       }

     

       124
       124
       +
       

     

       125
       125
       +
       func TestSecretMask_EmptySecretsFiltered(t *testing.T) {

     

       126
       126
       +
       	mask := NewSecretMask([]string{"ab", "validpassword", "", "xyz"})

     

       127
       127
       +
       

     

       128
       128
       +
       	input := "Using validpassword here"

     

       129
       129
       +
       	expected := "Using *** here"

     

       130
       130
       +
       

     

       131
       131
       +
       	result := mask.Mask(input)

     

       132
       132
       +
       	if result != expected {

     

       133
       133
       +
       		t.Errorf("expected %q, got %q", expected, result)

     

       134
       134
       +
       	}

     

       135
       135
       +
       }

+1 -1

spindle/motd

···

       20
       20
        
                             **

     

       21
       21
        
                               ********

     

       22
       22
        
       

     

       23
       23
       -
       This is a spindle server. More info at https://tangled.sh/@tangled.sh/core/tree/master/docs/spindle

     

       23
       23
       +
       This is a spindle server. More info at https://docs.tangled.org/spindles.html#spindles

     

       24
       24
        
       

     

       25
       25
        
       Most API routes are under /xrpc/

+1 -1

tailwind.config.js

···

       2
       2
        
       const colors = require("tailwindcss/colors");

     

       3
       3
        
       

     

       4
       4
        
       module.exports = {

     

       5
       5
       -
       	content: ["./appview/pages/templates/**/*.html", "./appview/pages/chroma.go"],

     

       5
       5
       +
       	content: ["./appview/pages/templates/**/*.html", "./appview/pages/chroma.go", "./docs/*.html"],

     

       6
       6
        
       	darkMode: "media",

     

       7
       7
        
       	theme: {

     

       8
       8
        
       		container: {

types/diff.go

···

       74
       74
        
       

     

       75
       75
        
       // used by html elements as a unique ID for hrefs

     

       76
       76
        
       func (d *Diff) Id() string {

     

       77
       77
       +
       	if d.IsDelete {

     

       78
       78
       +
       		return d.Name.Old

     

       79
       79
       +
       	}

     

       77
       80
        
       	return d.Name.New

     

       78
       81
        
       }

     

       79
       82

+112

types/diff_test.go

···

       1
       1
       +
       package types

     

       2
       2
       +
       

     

       3
       3
       +
       import "testing"

     

       4
       4
       +
       

     

       5
       5
       +
       func TestDiffId(t *testing.T) {

     

       6
       6
       +
       	tests := []struct {

     

       7
       7
       +
       		name     string

     

       8
       8
       +
       		diff     Diff

     

       9
       9
       +
       		expected string

     

       10
       10
       +
       	}{

     

       11
       11
       +
       		{

     

       12
       12
       +
       			name: "regular file uses new name",

     

       13
       13
       +
       			diff: Diff{

     

       14
       14
       +
       				Name: struct {

     

       15
       15
       +
       					Old string `json:"old"`

     

       16
       16
       +
       					New string `json:"new"`

     

       17
       17
       +
       				}{Old: "", New: "src/main.go"},

     

       18
       18
       +
       			},

     

       19
       19
       +
       			expected: "src/main.go",

     

       20
       20
       +
       		},

     

       21
       21
       +
       		{

     

       22
       22
       +
       			name: "new file uses new name",

     

       23
       23
       +
       			diff: Diff{

     

       24
       24
       +
       				Name: struct {

     

       25
       25
       +
       					Old string `json:"old"`

     

       26
       26
       +
       					New string `json:"new"`

     

       27
       27
       +
       				}{Old: "", New: "src/new.go"},

     

       28
       28
       +
       				IsNew: true,

     

       29
       29
       +
       			},

     

       30
       30
       +
       			expected: "src/new.go",

     

       31
       31
       +
       		},

     

       32
       32
       +
       		{

     

       33
       33
       +
       			name: "deleted file uses old name",

     

       34
       34
       +
       			diff: Diff{

     

       35
       35
       +
       				Name: struct {

     

       36
       36
       +
       					Old string `json:"old"`

     

       37
       37
       +
       					New string `json:"new"`

     

       38
       38
       +
       				}{Old: "src/deleted.go", New: ""},

     

       39
       39
       +
       				IsDelete: true,

     

       40
       40
       +
       			},

     

       41
       41
       +
       			expected: "src/deleted.go",

     

       42
       42
       +
       		},

     

       43
       43
       +
       		{

     

       44
       44
       +
       			name: "renamed file uses new name",

     

       45
       45
       +
       			diff: Diff{

     

       46
       46
       +
       				Name: struct {

     

       47
       47
       +
       					Old string `json:"old"`

     

       48
       48
       +
       					New string `json:"new"`

     

       49
       49
       +
       				}{Old: "src/old.go", New: "src/renamed.go"},

     

       50
       50
       +
       				IsRename: true,

     

       51
       51
       +
       			},

     

       52
       52
       +
       			expected: "src/renamed.go",

     

       53
       53
       +
       		},

     

       54
       54
       +
       	}

     

       55
       55
       +
       

     

       56
       56
       +
       	for _, tt := range tests {

     

       57
       57
       +
       		t.Run(tt.name, func(t *testing.T) {

     

       58
       58
       +
       			if got := tt.diff.Id(); got != tt.expected {

     

       59
       59
       +
       				t.Errorf("Diff.Id() = %q, want %q", got, tt.expected)

     

       60
       60
       +
       			}

     

       61
       61
       +
       		})

     

       62
       62
       +
       	}

     

       63
       63
       +
       }

     

       64
       64
       +
       

     

       65
       65
       +
       func TestChangedFilesMatchesDiffId(t *testing.T) {

     

       66
       66
       +
       	// ChangedFiles() must return values matching each Diff's Id()

     

       67
       67
       +
       	// so that sidebar links point to the correct anchors.

     

       68
       68
       +
       	// Tests existing, deleted, new, and renamed files.

     

       69
       69
       +
       	nd := NiceDiff{

     

       70
       70
       +
       		Diff: []Diff{

     

       71
       71
       +
       			{

     

       72
       72
       +
       				Name: struct {

     

       73
       73
       +
       					Old string `json:"old"`

     

       74
       74
       +
       					New string `json:"new"`

     

       75
       75
       +
       				}{Old: "", New: "src/modified.go"},

     

       76
       76
       +
       			},

     

       77
       77
       +
       			{

     

       78
       78
       +
       				Name: struct {

     

       79
       79
       +
       					Old string `json:"old"`

     

       80
       80
       +
       					New string `json:"new"`

     

       81
       81
       +
       				}{Old: "src/deleted.go", New: ""},

     

       82
       82
       +
       				IsDelete: true,

     

       83
       83
       +
       			},

     

       84
       84
       +
       			{

     

       85
       85
       +
       				Name: struct {

     

       86
       86
       +
       					Old string `json:"old"`

     

       87
       87
       +
       					New string `json:"new"`

     

       88
       88
       +
       				}{Old: "", New: "src/new.go"},

     

       89
       89
       +
       				IsNew: true,

     

       90
       90
       +
       			},

     

       91
       91
       +
       			{

     

       92
       92
       +
       				Name: struct {

     

       93
       93
       +
       					Old string `json:"old"`

     

       94
       94
       +
       					New string `json:"new"`

     

       95
       95
       +
       				}{Old: "src/old.go", New: "src/renamed.go"},

     

       96
       96
       +
       				IsRename: true,

     

       97
       97
       +
       			},

     

       98
       98
       +
       		},

     

       99
       99
       +
       	}

     

       100
       100
       +
       

     

       101
       101
       +
       	changedFiles := nd.ChangedFiles()

     

       102
       102
       +
       

     

       103
       103
       +
       	if len(changedFiles) != len(nd.Diff) {

     

       104
       104
       +
       		t.Fatalf("ChangedFiles() returned %d items, want %d", len(changedFiles), len(nd.Diff))

     

       105
       105
       +
       	}

     

       106
       106
       +
       

     

       107
       107
       +
       	for i, diff := range nd.Diff {

     

       108
       108
       +
       		if changedFiles[i] != diff.Id() {

     

       109
       109
       +
       			t.Errorf("ChangedFiles()[%d] = %q, but Diff.Id() = %q", i, changedFiles[i], diff.Id())

     

       110
       110
       +
       		}

     

       111
       111
       +
       	}

     

       112
       112
       +
       }

Compare changes