Help us shape the future of Go! Take the 2026 Go Developer Survey

render

package
v2.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 10, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package render turns the server's model into the readable half of a tool result, and prepares text other people wrote before anything shows it (docs/architecture.md §4.1, §4.8).

The preparation is the part that matters for safety: hidden text is removed and counted, links show where they go, long text is cut at a budget that is stated, and everything someone else wrote is rendered inside a boundary whose token is drawn per call, so the content cannot close it.

Index

Constants

View Source 
const (
	// DescriptionBudget bounds an issue or merge request description.
	DescriptionBudget = 20000
	// FileBudget bounds the text of one file.
	FileBudget = 60000
	// DiscussionBudget bounds the comment text of one page of threads.
	DiscussionBudget = 30000
	// NoteBudget bounds one comment within that.
	NoteBudget = 6000
	// DiffBudget bounds the diffs of one commit.
	DiffBudget = 40000
	// CommitMessageBudget bounds a commit message.
	CommitMessageBudget = 8000
	// TestReportBudget bounds the failed cases of one test report
	// result, and TestOutputBudget one case's output within that.
	TestReportBudget = 40000
	TestOutputBudget = 4000
	// BoardsBudget bounds one page of list_boards, by an estimate of
	// each board's lists.
	BoardsBudget = 30000
	// BoardsRead is how many boards one list_boards call reads, the
	// first by id.
	BoardsRead = 1000
	// TitleChars bounds a one-line title.
	TitleChars = 200
)

Budgets in characters (§4.8). A result states the one it used, so a cut text is never mistaken for a short one.

View Source 
const (
	JobLogBytes    = 40000
	MaxJobLogBytes = 100000
)

JobLogBytes is the default window of a job log, in bytes of the stored log, and MaxJobLogBytes the most one call reads (§4.8).

View Source 
const SuggestionLen = 2000

SuggestionLen caps each text of a suggestion a result shows.

View Source 
const TimestampPrefix = `[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?Z [0-9a-fA-F]{2}[OE](\+| ?)`

TimestampPrefix matches a runner's per-line timestamp and stream marker; group 1 is "+" on a line that continues the one before.

Variables

This section is empty.

Functions

func ApprovalWrite 

func ApprovalWrite(w model.ApprovalWrite, _ Boundary) string

ApprovalWrite renders approve_merge_request and unapprove_merge_request.

func Artifact 

func Artifact(a model.Artifact, bd Boundary) string

Artifact renders get_job_artifact.

func Artifacts 

func Artifacts(l model.Artifacts, _ Boundary) string

Artifacts renders list_job_artifacts.

func AutoMergeCancel added in v2.2.0 

func AutoMergeCancel(w model.AutoMergeCancel, _ Boundary) string

AutoMergeCancel renders cancel_auto_merge.

func Blame 

func Blame(bl model.Blame, bd Boundary) string

Blame renders get_blame.

func Boards added in v2.1.0 

func Boards(l model.Boards, bd Boundary) string

Boards renders list_boards.

func BranchDelete 

func BranchDelete(w model.BranchDelete, _ Boundary) string

BranchDelete renders delete_branch.

func BranchWrite 

func BranchWrite(w model.BranchWrite, _ Boundary) string

BranchWrite renders create_branch.

func Branches 

func Branches(l model.Branches, bd Boundary) string

Branches renders list_branches.

func Code 

func Code(s string) (string, int)

Code prepares text that is not rendered as Markdown — file contents, diffs, commit messages. Nothing is dropped, because the text may be edited later on the strength of what was shown; each hidden character is written out as <U+202E> instead, which is also how a reviewer would want to see it. It returns the text and how many were made visible.

func CommentDelete 

func CommentDelete(w model.CommentDelete, _ Boundary) string

CommentDelete renders delete_comment.

func CommentUpdate 

func CommentUpdate(w model.CommentUpdate, _ Boundary) string

CommentUpdate renders update_comment.

func CommentWrite 

func CommentWrite(w model.CommentWrite, _ Boundary) string

CommentWrite renders add_comment and add_review_comment.

func Commit 

func Commit(c model.Commit, bd Boundary) string

Commit renders get_commit.

func CommitWrite 

func CommitWrite(w model.CommitWrite, _ Boundary) string

CommitWrite renders create_commit.

func Commits 

func Commits(l model.Commits, bd Boundary) string

Commits renders list_commits.

func Compare 

func Compare(c model.Compare, bd Boundary) string

Compare renders compare_refs.

func ContentType 

func ContentType(b []byte) string

ContentType guesses a media type from the first bytes.

func Cut 

func Cut(text string, offset, budget int) (string, model.Budget)

Cut returns the part of text that starts at offset and fits budget, ending at a paragraph boundary when one falls in the second half of the window, else at a line boundary there, else at the budget. Offsets and counts are in characters (runes), never bytes, so a continue offset never lands inside one.

An offset past the end yields nothing and a budget whose ContinueOffset is null; the caller decides whether that is an error.

func Deployments 

func Deployments(l model.Deployments, _ Boundary) string

Deployments renders list_deployments.

func DiscussionWrite 

func DiscussionWrite(w model.DiscussionWrite, _ Boundary) string

DiscussionWrite renders resolve_discussion.

func Discussions 

func Discussions(d model.Discussions, bd Boundary) string

Discussions renders list_discussions.

func DraftDelete 

func DraftDelete(w model.DraftDelete, _ Boundary) string

DraftDelete renders delete_review_comment.

func DraftNotes 

func DraftNotes(d model.DraftNotes, bd Boundary) string

DraftNotes renders list_review_comments.

func DraftPublish added in v2.2.0 

func DraftPublish(w model.DraftPublish, bd Boundary) string

DraftPublish renders publish_review_comment. A lost draft's text is shown in a boundary: a draft may quote anyone.

func DraftUpdate added in v2.2.0 

func DraftUpdate(w model.DraftUpdate, _ Boundary) string

DraftUpdate renders update_review_comment.

func Environments 

func Environments(l model.Environments, _ Boundary) string

Environments renders list_environments.

func Events 

func Events(l model.Events, bd Boundary) string

Events renders list_events.

func File 

func File(f model.File, bd Boundary) string

File renders get_file.

func Ident 

func Ident(s string) string

Ident prepares a name someone else chose — a file path, a branch, a label, a topic — for one line of text. Nothing is dropped, folded or cut, since the name may be passed back to a tool; each control or hidden character is written out as <U+000A> instead, so a newline in a file name cannot start a line that reads as the server's.

func Invisible added in v2.2.0 

func Invisible(s string) []rune

Invisible lists the characters of s a reader would not see, each once, in order: hidden and bidirectional ones, characters drawn as blank space, and controls other than tab, line feed and carriage return. Unicode's other default-ignorable characters, the Hangul fillers among them, and the variation selectors are included: a filler is an identifier that reads as nothing, and a selector makes two names that read the same (\u00A74.12).

func IsBinary 

func IsBinary(b []byte) bool

IsBinary reports content that is not text: a NUL byte, or bytes that are not UTF-8, in the first 8,000. Binary content is described by its metadata, never shown as lossy text (§4.8).

func Issue 

func Issue(is model.Issue, bd Boundary) string

Issue renders get_issue.

func IssueLinkWrite 

func IssueLinkWrite(w model.IssueLinkWrite, _ Boundary) string

IssueLinkWrite renders link_issues and unlink_issues.

func IssueMove 

func IssueMove(w model.IssueMove, _ Boundary) string

IssueMove renders move_issue.

func IssueWrite 

func IssueWrite(w model.IssueWrite, _ Boundary) string

IssueWrite renders create_issue and update_issue.

func ItemEvents added in v2.1.0 

func ItemEvents(l model.ItemEvents, bd Boundary) string

ItemEvents renders list_item_events.

func ItemList 

func ItemList(l model.ItemList, noun string, bd Boundary) string

ItemList renders search_issues and search_merge_requests. noun is "issues" or "merge requests".

func JobLog 

func JobLog(l model.JobLog, bd Boundary) string

JobLog renders get_job_log.

func JobWrite 

func JobWrite(w model.JobWrite, _ Boundary) string

JobWrite renders retry_job and play_job.

func Jobs 

func Jobs(l model.Jobs, _ Boundary) string

Jobs renders list_jobs.

func LabelWrite 

func LabelWrite(w model.LabelWrite, bd Boundary) string

LabelWrite renders create_label, update_label and delete_label.

func Labels 

func Labels(l model.Labels, bd Boundary) string

Labels renders list_labels.

func Line 

func Line(s string, max int) (string, int)

Line prepares a one-line field someone else wrote, such as a title: hidden characters dropped, runs of spaces and control characters (line and paragraph separators included) folded to one space, and the result cut to max characters. It returns the line and how many characters were dropped. 

func Links(s, self string) string

Links rewrites Markdown links so the text shows where they go (§4.1.3). A link whose text says one thing and whose destination is another is the cheapest deception there is, and nothing is ever fetched, so what the reader needs is the host. A link on the configured instance, self, keeps its path, because that is how an issue points at another issue.

func Lint 

func Lint(l model.Lint, bd Boundary) string

Lint renders lint_ci.

func Log 

func Log(raw []byte) string

Log turns a window of a stored log into the text GitLab's job page shows (see above). It does not mask secrets or make hidden characters visible; the caller does both, on what this returns.

func MRCommits 

func MRCommits(c model.MRCommits, bd Boundary) string

MRCommits renders list_mr_commits.

func MRDiff 

func MRDiff(d model.MRDiff, bd Boundary) string

MRDiff renders get_mr_diff.

func MRFiles 

func MRFiles(f model.MRFiles, _ Boundary) string

MRFiles renders list_mr_files.

func MRVersionChanges added in v2.2.0 

func MRVersionChanges(c model.MRVersionChanges, bd Boundary) string

MRVersionChanges renders compare_mr_versions.

func MRVersions added in v2.2.0 

func MRVersions(v model.MRVersions, _ Boundary) string

MRVersions renders list_mr_versions.

func Markdown 

func Markdown(s string, self string) (string, int)

Markdown prepares Markdown someone else wrote for display: HTML comments and reference definitions no link uses, outside code fences, are dropped, hidden characters are dropped everywhere, and links show their destination. It returns the text and how many characters were dropped.

Comments inside a fence are left, because there they are visible: the rule is to remove what a person reading the page would not see and the model would.

func Me 

func Me(m model.Me, _ Boundary) string

Me renders get_me. It shows nothing that needs a boundary.

func Members 

func Members(l model.Members, _ Boundary) string

Members renders list_members.

func MergeRequest 

func MergeRequest(mr model.MergeRequest, bd Boundary) string

MergeRequest renders get_merge_request.

func MergeRequestPipelineWrite added in v2.1.0 

func MergeRequestPipelineWrite(w model.MergeRequestPipelineWrite, _ Boundary) string

MergeRequestPipelineWrite renders run_merge_request_pipeline.

func MergeRequestWrite 

func MergeRequestWrite(w model.MergeRequestWrite, _ Boundary) string

MergeRequestWrite renders create_merge_request and update_merge_request.

func MergeWrite 

func MergeWrite(w model.MergeWrite, _ Boundary) string

MergeWrite renders merge_merge_request.

func MilestoneWrite 

func MilestoneWrite(w model.MilestoneWrite, bd Boundary) string

MilestoneWrite renders create_milestone, update_milestone and delete_milestone.

func Milestones 

func Milestones(m model.Milestones, bd Boundary) string

Milestones renders list_milestones.

func PickWrite 

func PickWrite(w model.PickWrite, bd Boundary) string

PickWrite renders cherry_pick_commit and revert_commit.

func Pipeline 

func Pipeline(p model.PipelineDetail, bd Boundary) string

Pipeline renders get_pipeline.

func PipelineWrite 

func PipelineWrite(w model.PipelineWrite, _ Boundary) string

PipelineWrite renders run_pipeline, retry_pipeline and cancel_pipeline.

func Pipelines 

func Pipelines(l model.Pipelines, _ Boundary) string

Pipelines renders list_pipelines.

func Project 

func Project(p model.Project, bd Boundary) string

Project renders get_project.

func ProjectList 

func ProjectList(l model.ProjectList, bd Boundary) string

ProjectList renders search_projects.

func ReactionWrite added in v2.2.0 

func ReactionWrite(w model.ReactionWrite, _ Boundary) string

ReactionWrite renders react.

func RebaseWrite 

func RebaseWrite(w model.RebaseWrite, bd Boundary) string

RebaseWrite renders rebase_merge_request.

func Release 

func Release(r model.Release, bd Boundary) string

Release renders get_release.

func ReleaseWrite 

func ReleaseWrite(w model.ReleaseWrite, _ Boundary) string

ReleaseWrite renders create_release.

func Releases 

func Releases(l model.Releases, bd Boundary) string

Releases renders list_releases.

func Resolved 

func Resolved(r model.Resolved, _ Boundary) string

Resolved renders resolve_url. It shows nothing that needs a boundary.

func ReviewSubmit 

func ReviewSubmit(w model.ReviewSubmit, _ Boundary) string

ReviewSubmit renders submit_review. 

func Search(s model.Search, bd Boundary) string

Search renders search.

func Snippet 

func Snippet(s model.Snippet, bd Boundary) string

Snippet renders get_snippet.

func SnippetDelete added in v2.1.0 

func SnippetDelete(w model.SnippetDelete, _ Boundary) string

SnippetDelete renders delete_snippet.

func SnippetUpdate added in v2.1.0 

func SnippetUpdate(w model.SnippetUpdate, _ Boundary) string

SnippetUpdate renders update_snippet.

func SnippetWrite 

func SnippetWrite(w model.SnippetWrite, _ Boundary) string

SnippetWrite renders create_snippet.

func Snippets 

func Snippets(l model.Snippets, bd Boundary) string

Snippets renders list_snippets.

func StripANSI 

func StripANSI(s string) string

StripANSI removes terminal escapes, which also hide a secret from the masks: a color code before a token leaves no word boundary to match.

func SubscriptionWrite added in v2.1.0 

func SubscriptionWrite(w model.SubscriptionWrite, _ Boundary) string

SubscriptionWrite renders subscribe.

func SuggestionText added in v2.2.0 

func SuggestionText(from, to string) (fromShown, toShown string, cut bool, hidden int)

SuggestionText prepares a suggestion's two texts as Code prepares code, each cut at SuggestionLen characters: what a reader sees is what applying it commits.

func SuggestionsApply added in v2.2.0 

func SuggestionsApply(w model.SuggestionsApply, bd Boundary) string

SuggestionsApply renders apply_suggestions.

func TagWrite 

func TagWrite(w model.TagWrite, _ Boundary) string

TagWrite renders create_tag and delete_tag.

func Tags 

func Tags(t model.Tags, bd Boundary) string

Tags renders list_tags.

func TestReport added in v2.1.0 

func TestReport(r model.TestReport, bd Boundary) string

TestReport renders get_test_report.

func TimeWrite added in v2.1.0 

func TimeWrite(w model.TimeWrite, _ Boundary) string

TimeWrite renders track_time.

func TodoWrite added in v2.1.0 

func TodoWrite(w model.TodoWrite, _ Boundary) string

TodoWrite renders add_todo.

func Todos 

func Todos(l model.Todos, bd Boundary) string

Todos renders list_todos.

func TodosDone 

func TodosDone(w model.TodosDone, _ Boundary) string

TodosDone renders mark_todos_done.

func Tree 

func Tree(t model.Tree, _ Boundary) string

Tree renders list_tree.

func UploadWrite added in v2.3.0 

func UploadWrite(w model.UploadWrite, _ Boundary) string

UploadWrite renders upload_file. The Markdown is GitLab's, built from a name the server made safe, and stands in a code span so a client shows it rather than drawing the image.

func Users 

func Users(l model.Users, _ Boundary) string

Users renders find_users.

func WikiDelete 

func WikiDelete(w model.WikiDelete, _ Boundary) string

WikiDelete renders delete_wiki_page.

func WikiPage 

func WikiPage(p model.WikiPage, bd Boundary) string

WikiPage renders get_wiki_page.

func WikiPages 

func WikiPages(l model.WikiPages, bd Boundary) string

WikiPages renders list_wiki_pages.

func WikiWrite 

func WikiWrite(w model.WikiWrite, _ Boundary) string

WikiWrite renders save_wiki_page.

Types

type AskedSuggestion added in v2.2.0 

type AskedSuggestion struct {
	ID               int64
	Path             string
	FromLine, ToLine int
	To               string
}

AskedSuggestion is one suggestion AskApplySuggestions shows: where it goes and the text it commits.

type Boundary 

type Boundary struct {
	// contains filtered or unexported fields
}

Boundary marks text someone else wrote (§4.1.1). Its token is drawn per tool call, so text written before the call cannot know it and cannot close the block early: a forged end marker carries the wrong token. Markers are also defused inside the text, so a forgery does not even look like one.

func NewBoundary 

func NewBoundary() Boundary

NewBoundary draws a fresh token.

func (Boundary) Block 

func (b Boundary) Block(o Origin, text string) string

Block wraps multi-line text: 

<<<UNTRUSTED 0123abcd kind=description project=group/project item=#12 author=@alice>>>
text
<<<END 0123abcd>>>

func (Boundary) Inline 

func (b Boundary) Inline(text string) string

Inline wraps one line of text, such as a title, in place.

func (Boundary) Notice 

func (b Boundary) Notice() string

Notice is the line a result puts before its first block. It names the token, so the reader knows which markers are the server's.

func (Boundary) Token 

func (b Boundary) Token() string

Token is the per-call token.

type LogSection 

type LogSection struct {
	Name       string
	Start, End int
}

LogSection is one section of a stored log, by byte offsets: Start is where its start marker begins, or -1 when it began before the stretch read; End is where its end marker ends, or -1 when the stretch has no end marker for it.

func LogSections 

func LogSections(raw []byte) []LogSection

LogSections finds the sections of a stretch of a stored log, in the order their markers appear. A section whose end marker is in the stretch and whose start is not began before it.

type Origin 

type Origin struct {
	Kind    string
	Project string
	Item    string // "#12", "!3", a file path or a commit id
	Author  string // a username, without "@"
}

Origin says where a block of text came from: its kind, the project, the issue, merge request or path, and who wrote it.

type Question 

type Question struct {
	Text string
	Bind string
}

Question is what the server asks the person before a write that ships work or deletes something for good (§4.12). Text is the message a client shows; accepting it is the confirmation. Every word is the server's, except what stands in backticks, which is quoted from GitLab or from the call and cut to one line. A blank line separates the lines, so a client that draws Markdown keeps them apart.

Bind is what an answer is bound to: what the write depends on, which must not change between the question and the write. It is Text, and more where Text shows less than the write uses — a whole head sha, a whole comment.

func AskApplySuggestions added in v2.2.0 

func AskApplySuggestions(project string, iid int64, source, sha string, sgs []AskedSuggestion) Question

AskApplySuggestions asks before apply_suggestions: the text is someone else's, committed under the person's name. The head and each whole text are bound.

func AskApprove 

func AskApprove(project string, iid int64, title, sha string) Question

AskApprove asks before approve_merge_request.

func AskCreateRelease 

func AskCreateRelease(project, tag, name, ref string, tagExists bool, links int) Question

AskCreateRelease asks before create_release.

func AskCreateTag 

func AskCreateTag(project, name, ref string) Question

AskCreateTag asks before create_tag. A tag a protection rule would cover is refused before it is asked about.

func AskDeleteBranch 

func AskDeleteBranch(project, branch, sha string, merged bool) Question

AskDeleteBranch asks before delete_branch. The whole head is bound.

func AskDeleteComment 

func AskDeleteComment(project, kind string, iid int64, author, body string) Question

AskDeleteComment asks before delete_comment, showing the start of the comment; the whole comment is bound. kind is "issue" or "merge_request".

func AskDeleteLabel 

func AskDeleteLabel(project, name string, openIssues *int) Question

AskDeleteLabel asks before delete_label. The count is shown and not bound: a label that is applied while the person reads would never be confirmed. The label is bound by its name.

func AskDeleteMilestone 

func AskDeleteMilestone(project, title string) Question

AskDeleteMilestone asks before delete_milestone.

func AskDeleteSnippet added in v2.1.0 

func AskDeleteSnippet(project string, id int64, title string, files []string) Question

AskDeleteSnippet asks before delete_snippet; project is empty for a personal snippet. It counts the files and names each on its own line, the first askFiles of them. The whole title and every file name are bound.

func AskDeleteTag 

func AskDeleteTag(project, name, sha string, release bool) Question

AskDeleteTag asks before delete_tag. The whole commit is bound.

func AskDeleteWikiPage 

func AskDeleteWikiPage(project, title, slug string) Question

AskDeleteWikiPage asks before delete_wiki_page. The page's content is bound by the witness delete_wiki_page already holds.

func AskMerge 

func AskMerge(project string, iid int64, title, source, target, sha string, autoMerge bool, squash, removeSource *bool) Question

AskMerge asks before merge_merge_request, or before setting a merge request to merge when its pipeline succeeds. The whole head is bound.

func AskPlayJob 

func AskPlayJob(project string, jobID int64, name, stage string, pipelineID int64, variables, inputs []string) Question

AskPlayJob asks before play_job. Variable values are never shown, only their keys.

func AskPublishIssue 

func AskPublishIssue(project string, iid int64, title string) Question

AskPublishIssue asks before update_issue makes a confidential issue public.

func AskRunMergeRequestPipeline added in v2.1.0 

func AskRunMergeRequestPipeline(project string, iid int64, title, source, target, sha string, sourceKind, targetKind RefKind) Question

AskRunMergeRequestPipeline asks before run_merge_request_pipeline when both of the merge request's branches count as protected, so its jobs may see protected variables. The whole head and the branches are bound.

func AskRunPipeline 

func AskRunPipeline(project, ref string, kind RefKind, variables, inputs []string) Question

AskRunPipeline asks before run_pipeline on the default branch or a protected ref.

func AskUploadFile added in v2.3.0 

func AskUploadFile(project, name, contentType string, notes []string, data []byte) Question

AskUploadFile asks before upload_file: an upload discloses the image to whoever can open its link. notes are the server's own sentences on who can and what goes with it. The image's bytes are bound.

type RefKind 

type RefKind int

RefKind is why a pipeline's ref asks: it is the project's default branch, a protected branch or tag, or a ref whose protection cannot be told. 

const (
	DefaultBranch RefKind = iota + 1
	ProtectedBranch
	ProtectedTag
	// UnknownRef is a ref GitLab has no branch or tag by, whose
	// protection cannot be told.
	UnknownRef
)

The kinds of ref run_pipeline asks about.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.