| 1 | // Package cispec is de blue-ci-cd.yml-specificatie. |
| 2 | // De infopagina en GET /api/v1/ci/spec gebruiken allebei Build, zodat de |
| 3 | // tekst en de presets niet uit elkaar lopen. |
| 4 | package cispec |
| 5 | |
| 6 | import ( |
| 7 | "bytes" |
| 8 | "encoding/json" |
| 9 | |
| 10 | "gitlab.com/Timfa/bluegit/internal/i18n" |
| 11 | "gitlab.com/Timfa/bluegit/internal/images" |
| 12 | ) |
| 13 | |
| 14 | // Doc is het document dat de pagina tekent en de API teruggeeft. |
| 15 | type Doc struct { |
| 16 | File string `json:"file"` |
| 17 | Example string `json:"example"` |
| 18 | Sections []Section `json:"sections"` |
| 19 | } |
| 20 | |
| 21 | // Section is één blok: sleutelwoorden, variabelen, verschillen of presets. |
| 22 | type Section struct { |
| 23 | ID string `json:"id"` |
| 24 | Title string `json:"title"` |
| 25 | Intro string `json:"intro,omitempty"` |
| 26 | Kind string `json:"kind"` |
| 27 | Items []Item `json:"items,omitempty"` |
| 28 | Variables []Variable `json:"variables,omitempty"` |
| 29 | Lines []string `json:"lines,omitempty"` |
| 30 | Presets []Preset `json:"presets,omitempty"` |
| 31 | } |
| 32 | |
| 33 | // Item is één sleutelwoord. |
| 34 | type Item struct { |
| 35 | Name string `json:"name"` |
| 36 | Summary string `json:"summary"` |
| 37 | } |
| 38 | |
| 39 | // Variable is een voorgedefinieerde CI_-variabele. |
| 40 | // Scope is both, container of mr en blijft in het Engels, ook als de pagina vertaald is. |
| 41 | type Variable struct { |
| 42 | Name string `json:"name"` |
| 43 | Scope string `json:"scope"` |
| 44 | Where string `json:"where"` |
| 45 | Summary string `json:"summary"` |
| 46 | } |
| 47 | |
| 48 | // Preset is één image-alias zoals Steve die bouwt of mapt. |
| 49 | type Preset struct { |
| 50 | Name string `json:"name"` |
| 51 | Runtime string `json:"runtime"` |
| 52 | From string `json:"from"` |
| 53 | Tools []string `json:"tools"` |
| 54 | Mode string `json:"mode"` |
| 55 | } |
| 56 | |
| 57 | const example = `image: bluegit/base |
| 58 | unit: |
| 59 | stage: test |
| 60 | image: bluegit/node |
| 61 | script: |
| 62 | - node --version |
| 63 | plain: |
| 64 | stage: test |
| 65 | image: node:22 |
| 66 | script: |
| 67 | - node --version |
| 68 | ` |
| 69 | |
| 70 | // Build maakt het document in lang. presets nil gebruikt de ingebouwde lijst. |
| 71 | func Build(lang i18n.Lang, presets []images.Preset) Doc { |
| 72 | if presets == nil { |
| 73 | presets = images.Builtin() |
| 74 | } |
| 75 | t := func(key string) string { return i18n.T(lang, key) } |
| 76 | kw := func(name, key string) Item { return Item{Name: name, Summary: t(key)} } |
| 77 | where := map[string]string{ |
| 78 | "both": t("info.where.both"), |
| 79 | "container": t("info.where.container"), |
| 80 | "mr": t("info.where.mr"), |
| 81 | } |
| 82 | variable := func(name, scope string) Variable { |
| 83 | return Variable{Name: name, Scope: scope, Where: where[scope], Summary: t("info.var." + name)} |
| 84 | } |
| 85 | doc := Doc{ |
| 86 | File: "blue-ci-cd.yml", |
| 87 | Example: example, |
| 88 | Sections: []Section{ |
| 89 | { |
| 90 | ID: "pipeline", Title: t("info.sec.pipeline"), Kind: "keywords", |
| 91 | Items: []Item{ |
| 92 | kw("stages", "info.kw.stages"), |
| 93 | kw("variables", "info.kw.variables"), |
| 94 | kw("image", "info.kw.image"), |
| 95 | kw("default", "info.kw.default"), |
| 96 | kw("include", "info.kw.include"), |
| 97 | kw("before_script", "info.kw.before_script"), |
| 98 | kw("after_script", "info.kw.after_script"), |
| 99 | kw("cache", "info.kw.cache"), |
| 100 | kw("workflow", "info.kw.workflow"), |
| 101 | kw("jobs", "info.kw.jobs"), |
| 102 | }, |
| 103 | }, |
| 104 | { |
| 105 | ID: "jobs", Title: t("info.sec.job"), Kind: "keywords", |
| 106 | Items: []Item{ |
| 107 | kw("stage", "info.kw.stage"), |
| 108 | kw("image", "info.kw.image"), |
| 109 | kw("before_script", "info.kw.before_script"), |
| 110 | kw("script", "info.kw.script"), |
| 111 | kw("after_script", "info.kw.after_script"), |
| 112 | kw("needs", "info.kw.needs"), |
| 113 | kw("rules", "info.kw.rules"), |
| 114 | kw("only", "info.kw.only"), |
| 115 | kw("except", "info.kw.except"), |
| 116 | kw("when", "info.kw.when"), |
| 117 | kw("allow_failure", "info.kw.allow_failure"), |
| 118 | kw("artifacts", "info.kw.artifacts"), |
| 119 | kw("cache", "info.kw.cache"), |
| 120 | kw("resource_group", "info.kw.resource_group"), |
| 121 | kw("timeout", "info.kw.timeout"), |
| 122 | kw("retry", "info.kw.retry"), |
| 123 | kw("parallel", "info.kw.parallel"), |
| 124 | kw("services", "info.kw.services"), |
| 125 | kw("environment", "info.kw.environment"), |
| 126 | kw("interruptible", "info.kw.interruptible"), |
| 127 | kw("tags", "info.kw.tags"), |
| 128 | kw("extends", "info.kw.extends"), |
| 129 | }, |
| 130 | }, |
| 131 | { |
| 132 | ID: "rules", Title: t("info.sec.rules"), Kind: "keywords", |
| 133 | Intro: t("info.rules.intro"), |
| 134 | Items: []Item{ |
| 135 | kw("if", "info.kw.if"), |
| 136 | kw("changes", "info.kw.changes"), |
| 137 | kw("exists", "info.kw.exists"), |
| 138 | kw("when", "info.kw.when"), |
| 139 | }, |
| 140 | }, |
| 141 | { |
| 142 | ID: "variables", Title: t("info.sec.variables"), Kind: "variables", |
| 143 | Variables: []Variable{ |
| 144 | variable("CI", "both"), |
| 145 | variable("CI_CONFIG_PATH", "both"), |
| 146 | variable("CI_SERVER_NAME", "both"), |
| 147 | variable("CI_COMMIT_SHA", "both"), |
| 148 | variable("CI_COMMIT_SHORT_SHA", "both"), |
| 149 | variable("CI_COMMIT_REF", "both"), |
| 150 | variable("CI_COMMIT_REF_NAME", "both"), |
| 151 | variable("CI_COMMIT_REF_SLUG", "both"), |
| 152 | variable("CI_COMMIT_TITLE", "both"), |
| 153 | variable("CI_COMMIT_TIMESTAMP", "both"), |
| 154 | variable("CI_COMMIT_BRANCH", "both"), |
| 155 | variable("CI_COMMIT_TAG", "both"), |
| 156 | variable("CI_DEFAULT_BRANCH", "both"), |
| 157 | variable("CI_PIPELINE_ID", "both"), |
| 158 | variable("CI_PIPELINE_SOURCE", "both"), |
| 159 | variable("CI_PIPELINE_URL", "both"), |
| 160 | variable("CI_PROJECT_PATH", "both"), |
| 161 | variable("CI_PROJECT_NAME", "both"), |
| 162 | variable("CI_PROJECT_NAMESPACE", "both"), |
| 163 | variable("CI_PROJECT_URL", "both"), |
| 164 | variable("CI_API_URL", "both"), |
| 165 | variable("CI_JOB_ID", "container"), |
| 166 | variable("CI_JOB_NAME", "container"), |
| 167 | variable("CI_JOB_STAGE", "container"), |
| 168 | variable("CI_JOB_URL", "container"), |
| 169 | variable("CI_JOB_TOKEN", "container"), |
| 170 | variable("CI_NODE_INDEX", "container"), |
| 171 | variable("CI_NODE_TOTAL", "container"), |
| 172 | variable("CI_ENVIRONMENT_NAME", "container"), |
| 173 | variable("CI_ENVIRONMENT_URL", "container"), |
| 174 | variable("CI_MERGE_REQUEST_ID", "mr"), |
| 175 | variable("CI_MERGE_REQUEST_IID", "mr"), |
| 176 | variable("CI_MERGE_REQUEST_TITLE", "mr"), |
| 177 | variable("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME", "mr"), |
| 178 | variable("CI_MERGE_REQUEST_SOURCE_BRANCH_SHA", "mr"), |
| 179 | variable("CI_MERGE_REQUEST_TARGET_BRANCH_NAME", "mr"), |
| 180 | variable("CI_MERGE_REQUEST_TARGET_BRANCH_SHA", "mr"), |
| 181 | variable("CI_MERGE_REQUEST_PROJECT_PATH", "mr"), |
| 182 | variable("CI_MERGE_REQUEST_PROJECT_URL", "mr"), |
| 183 | }, |
| 184 | }, |
| 185 | { |
| 186 | ID: "differences", Title: t("info.sec.diff"), Kind: "list", |
| 187 | Lines: []string{ |
| 188 | t("info.diff.file"), |
| 189 | t("info.diff.runner"), |
| 190 | t("info.diff.include"), |
| 191 | t("info.diff.unsupported"), |
| 192 | t("info.diff.services"), |
| 193 | t("info.diff.env"), |
| 194 | t("info.diff.retry"), |
| 195 | t("info.diff.parallel"), |
| 196 | t("info.diff.rules"), |
| 197 | t("info.diff.mr"), |
| 198 | t("info.diff.cache"), |
| 199 | t("info.diff.images"), |
| 200 | }, |
| 201 | }, |
| 202 | { |
| 203 | ID: "presets", Title: t("info.sec.presets"), Kind: "presets", |
| 204 | Intro: t("info.presets.intro") + " " + t("info.presets.config"), |
| 205 | Presets: presetDocs(presets), |
| 206 | }, |
| 207 | }, |
| 208 | } |
| 209 | return doc |
| 210 | } |
| 211 | |
| 212 | func presetDocs(in []images.Preset) []Preset { |
| 213 | out := make([]Preset, 0, len(in)) |
| 214 | for _, p := range in { |
| 215 | mode := "dockerfile" |
| 216 | if p.Direct != "" { |
| 217 | mode = "image" |
| 218 | } |
| 219 | tools := p.Tools |
| 220 | if tools == nil { |
| 221 | tools = []string{} |
| 222 | } |
| 223 | out = append(out, Preset{ |
| 224 | Name: p.Name, Runtime: p.Runtime, From: p.From, Tools: tools, Mode: mode, |
| 225 | }) |
| 226 | } |
| 227 | return out |
| 228 | } |
| 229 | |
| 230 | // Marshal is de JSON die de pagina in het scriptblok zet en de API schrijft. |
| 231 | func Marshal(doc Doc) []byte { |
| 232 | var buf bytes.Buffer |
| 233 | enc := json.NewEncoder(&buf) |
| 234 | enc.SetEscapeHTML(true) |
| 235 | _ = enc.Encode(doc) |
| 236 | return buf.Bytes() |
| 237 | } |