DS ForgeCourses
기존 Lab

운영 코드로 배우는 Go

Go,껍데기 제거

문법 요약이 아니라 요청, 저장, goroutine, 실패, 복구, 관측을 한 서비스에서 추적합니다.

CAPSTONE · MULTI-TENANT NOTIFICATION SERVICE

요청 한 번이 복구 가능한 알림이 되기까지

HTTP 경계에서 tenant와 idempotency key를 검증하고, DB commit 뒤 bounded worker가 provider를 호출합니다. unknown outcome은 retry와 reconciliation으로 수렴시키며 전체 경로를 trace·metric·profile로 관찰합니다.

  1. 01HTTP 요청
  2. 02tenant 경계
  3. 03DB commit
  4. 04bounded worker
  5. 05provider
  6. 06retry · reconcile
  7. 07trace · metric · profile
01

실패가 설계의 입력이다

provider timeout, 중복 전달, process kill, queue saturation, shutdown deadline을 테스트에서 의도적으로 만듭니다.

02

60초 기동 경로

go run ./cmd/notifier

P00 — P10 · 11 MODULES

runtime에서 runbook까지 한 페이지로

모듈 hash를 공유하고, 16개 공통 렌즈로 개념과 실제 artifact를 왕복하세요.

11 개 모듈0/11 완료

P00P00 · Go 컴파일과 runtime소스가 기계어와 runtime 메타데이터가 되고, goroutine이 실행·중단·회수되는 경계를 추적한다.16 sections#p00

학습 목표

  • 컴파일·링크·초기화·실행 순서를 설명한다.
  • stack, escape, heap, GC와 scheduler를 관측 도구로 확인한다.

필수 주제

source → compiler → binarypackage initializationgoroutine stack과 stack growthescape analysis와 heap allocationGCG/M/P scheduler와 work stealingsyscall, network poller, preemptioncgo 경계

직접 만들 산출물

  • lab/runtime
  • profiles
  • cmd/notifier/main.go

1. 실체와 오해

VERIFIED BEHAVIOR

goroutine은 OS thread의 별칭이 아니며, 작은 stack도 고정 크기 약속이 아니다.

SPEC

Go 사양은 goroutine의 언어 동작과 초기화 순서를 정하지만 G/M/P 구조를 약속하지 않는다.

VERIFIED BEHAVIOR

gc toolchain의 runtime은 현재 goroutine(G), OS thread(M), 실행 권한과 로컬 실행 큐(P)를 사용한다. 이는 버전 의존 구현이다.

2. 선수 지식

RECOMMENDED PRACTICE

함수 호출, pointer, process/thread, virtual memory와 터미널 사용을 먼저 복습한다.

PROJECT POLICY

실습은 CGO_ENABLED=0 기본 경로와 cgo 비교 경로를 분리하며 macOS와 Windows 명령을 함께 둔다.

3. 15분 개념

SPEC

컴파일러가 package별 object를 만들고 linker가 실행 파일을 만든 뒤, import dependency 순서의 package initialization을 거쳐 main.main이 실행된다.

main이 반환하면 다른 goroutine을 기다리지 않고 프로그램이 끝난다.

SPEC

import된 package는 importer보다 먼저 한 번 초기화되고, package 변수와 init 함수는 정의된 규칙에 따라 순차 실행된다.

RECOMMENDED PRACTICE

init에는 실패하기 쉬운 I/O나 숨은 goroutine을 넣지 말고 명시적 constructor에서 오류를 반환한다.

4. runtime 내부

VERIFIED BEHAVIOR

stack은 필요할 때 성장·이동할 수 있고 compiler/runtime이 pointer를 조정한다. escape analysis는 값의 수명을 보수적으로 분석해 stack 또는 heap 배치를 결정한다.

VERIFIED BEHAVIOR

현재 gc runtime은 concurrent mark-and-sweep 계열 GC, per-P run queue, global queue, work stealing, syscall handoff와 integrated network poller를 사용한다.

VERIFIED BEHAVIOR

asynchronous preemption과 safe point 세부는 release와 architecture에 따라 달라질 수 있어 latency 예산을 보장하지 않는다.

RECOMMENDED PRACTICE

cgo 호출은 scheduler, callback, pointer 전달, build portability와 진단 경계를 추가한다. 필요성과 비용을 별도로 측정한다.

5. 최소 코드

VERIFIED BEHAVIOR

escape report와 execution trace를 같은 작은 프로그램에서 비교한다.

RECOMMENDED PRACTICE

escape 메시지는 성능 판정이 아니라 조사 출발점이다. allocation profile로 실제 hot path를 확인한다.

go build -gcflags=-m=2 ./lab/runtime; go run ./lab/runtime
package main

import (
    "runtime/trace"
    "os"
)

func boxed(v int) *int { return &v }

func main() {
    f, _ := os.Create("trace.out")
    defer f.Close()
    _ = trace.Start(f)
    defer trace.Stop()
    done := make(chan *int)
    go func() { done <- boxed(42) }()
    <-done
}

6. production 확장

RECOMMENDED PRACTICE

notification 요청의 handler, transaction, worker와 provider 호출을 하나의 latency budget으로 연결한다.

PROJECT POLICY

GOMAXPROCS, GOMEMLIMIT, GC 비율은 환경 설정이며 고정 마법값으로 코드에 숨기지 않는다.

RECOMMENDED PRACTICE

container CPU·memory limit 아래에서 queue saturation, GC CPU, heap goal, goroutine 수를 함께 관찰한다.

7. 코드 해부

VERIFIED BEHAVIOR

handler가 job을 heap에 보낸다고 단정하지 말고 compiler report, benchmark allocs, heap profile을 차례로 대조한다.

VERIFIED BEHAVIOR

channel send 자체가 항상 allocation을 뜻하지 않는다. escape는 값·closure·channel lifetime과 compiler 최적화에 좌우된다.

RECOMMENDED PRACTICE

runtime 함수명이나 내부 struct field에 의존하는 production 코드는 release upgrade에 취약하다.

8. 호출·goroutine·memory trace

VERIFIED BEHAVIOR

HTTP goroutine이 DB wait로 막히고 worker가 provider network I/O에서 대기할 때, 실행 가능한 G와 parked G, M/P의 변화를 trace로 구분한다.

VERIFIED BEHAVIOR

execution trace는 scheduling, syscall, network wait, GC event를 관찰하지만 distributed request causality를 자동 증명하지 않는다.

PROJECT POLICY

trace artifact에는 Go version, GOOS, GOARCH, workload와 duration을 같이 기록한다.

9. 실패 주입

PROJECT POLICY

무한 재귀로 stack growth를, blocking syscall과 과도한 goroutine 생성으로 scheduler 압력을 재현하되 격리된 test process에서만 실행한다.

PROJECT POLICY

OOM과 cgo crash 실습은 기본 test suite에서 제외하고 build tag와 timeout으로 격리한다.

RECOMMENDED PRACTICE

실패 전후 goroutine dump와 runtime/metrics를 저장해 원인과 증상을 구분한다.

10. 테스트

PROJECT POLICY

runtime 내부 수치가 아니라 사용자 관찰 가능 invariant를 검증한다.

PROJECT POLICY

테스트는 package initialization 순서, main 종료 semantics와 leak-free cancellation을 검증하되 G/M/P 정확한 scheduling 순서는 가정하지 않는다.

RECOMMENDED PRACTICE

release별 비교는 go version을 결과에 포함한 benchmark/trace regression으로 관리한다.

11. 성능

RECOMMENDED PRACTICE

ns/op만 보고 결론 내리지 말고 B/op, allocs/op, CPU/heap profile과 scheduler latency를 함께 본다.

VERIFIED BEHAVIOR

compiler optimization과 GC/runtime 변화 때문에 benchmark 절대값은 Go release와 machine에 의존한다.

PROJECT POLICY

optimization은 representative workload profile과 before/after confidence interval이 있을 때만 채택한다.

12. 보안

RECOMMENDED PRACTICE

runtime 진단 endpoint와 cgo는 별도 attack surface다.

PROJECT POLICY

pprof와 trace endpoint는 public listener에 노출하지 않고 인증·network policy·수집 시간 제한을 둔다.

RECOMMENDED PRACTICE

cgo boundary에서 Go pointer 전달 규칙과 native dependency patch provenance를 검토한다.

13. 운영

RECOMMENDED PRACTICE

GC pause 하나보다 heap trend, allocation rate, CPU throttling, runnable goroutine과 queue wait의 상관을 운영 신호로 사용한다.

PROJECT POLICY

Go release 변경은 canary에서 profile/trace와 SLO를 비교한 뒤 rollback 가능한 artifact로 승격한다.

14. 산출물

PROJECT POLICY

escape.txt, trace.out, CPU/heap profile, annotated scheduler diagram과 cgo boundary note를 남긴다.

PROJECT POLICY

산출물 경로는 lab/runtime과 profiles이며 생성 명령·환경을 README에 기록한다.

15. 완료 조건

PROJECT POLICY

source→binary와 package initialization을 설명하고, stack/escape/GC/G-M-P/syscall/network poller/preemption/cgo 경계를 trace와 profile 근거로 구분하면 완료다.

PROJECT POLICY

function 검증은 명령 실행, quality 검증은 재현 가능한 증거, product 검증은 실제 학습자 과제 성공으로 따로 기록한다.

16. 자가시험

SPEC

질문: package init 중 시작한 goroutine은 다음 init보다 반드시 먼저 끝나는가? escape한 값은 영원히 heap에 남는가? syscall에서 돌아온 G는 같은 P에서 재개되는가?

SPEC

main 시작 전 init 함수 호출 자체는 순차지만 init이 만든 goroutine 완료는 보장되지 않는다.

자가시험 힌트

세 답은 모두 아니다. 첫째는 동시 실행 가능, 둘째는 reachability에 따라 GC 대상, 셋째는 scheduler 구현 선택이다.

P01P01 · Go 언어 실무값 복사, descriptor 공유, method set과 interface의 경계를 장애 코드로 확인한다.16 sections#p01

학습 목표

  • array·slice·map·string의 복사와 공유를 구분한다.
  • method set, interface nil, generics, defer와 panic 경계를 정확히 사용한다.

필수 주제

value semantics와 pointerarray, slice header, append와 capacity, backing array 공유map과 iteration 특성string, byte, runestruct와 embeddingmethod set, pointer/value receiverinterface representation과 nil interfacegenerics, defer, panic/recover

직접 만들 산출물

  • lab/language
  • lab/failures

1. 실체와 오해

SPEC

Go가 모두 값이라는 말은 복사 뒤 독립이라는 뜻이 아니다. slice와 map 값은 공유 storage에 접근할 수 있다.

SPEC

array 대입은 모든 element를 복사한다. slice 값은 underlying array 구간을 설명하며 대입은 그 descriptor를 복사한다.

SPEC

map iteration 순서는 지정되지 않으며 한 iteration에서 생성·삭제한 entry의 관찰도 제한적으로만 정의된다.

2. 선수 지식

RECOMMENDED PRACTICE

zero value, assignability, addressability, UTF-8과 dynamic/static type을 복습한다.

PROJECT POLICY

예제는 unsafe나 reflection 내부 layout을 언어 보장처럼 가르치지 않는다.

3. 15분 개념

SPEC

pointer는 값의 주소를 간접 참조한다. struct embedding은 상속이 아니라 field/method promotion 규칙이다.

string은 byte sequence이며 range는 UTF-8을 decode해 rune과 byte index를 낸다. byte 수와 문자 수는 다를 수 있다.

SPEC

T와 *T의 method set은 다르며 pointer receiver method는 일반적으로 *T의 method set에 속한다. addressable value의 편의 호출이 interface 구현을 바꾸지는 않는다.

SPEC

defer argument는 defer 문 실행 시 평가되고 호출은 surrounding function 반환 직전에 LIFO로 실행된다.

4. runtime 내부

VERIFIED BEHAVIOR

slice는 pointer·length·capacity 성격의 descriptor이고 interface value는 dynamic type과 dynamic value를 담는 것으로 모델링할 수 있지만, 구체적 메모리 layout은 사양이 아니다.

SPEC

nil interface는 dynamic type과 value가 모두 없는 interface다. typed nil pointer를 담은 interface는 nil과 같지 않다.

VERIFIED BEHAVIOR

append는 capacity가 충분하면 기존 backing array를 재사용할 수 있고, 부족하면 새 array를 할당할 수 있다. 정확한 growth policy는 구현 세부다.

5. 최소 코드

SPEC

작은 함수로 backing array alias와 typed nil interface를 동시에 드러낸다.

RECOMMENDED PRACTICE

ownership을 넘길 때 명확한 복제에는 slices.Clone 또는 copy를 사용한다.

package main

import "fmt"

type problem struct{}
func (*problem) Error() string { return "problem" }

func maybeError() error {
    var p *problem
    return p // dynamic type exists: result != nil
}

func main() {
    original := []string{"queued", "sent"}
    view := original[:1]
    view = append(view, "retry") // may overwrite original[1]
    fmt.Println(original, maybeError() == nil)
}

6. production 확장

RECOMMENDED PRACTICE

tenant payload를 validate한 뒤 mutable buffer의 ownership을 handler에서 worker로 명시적으로 이전하거나 복제한다.

PROJECT POLICY

API와 queue 경계에서는 []byte, map, pointer가 caller와 backing storage를 공유하지 않도록 clone 또는 immutable encoding을 사용한다.

RECOMMENDED PRACTICE

embedding으로 dependency를 노출시키지 말고 필요한 behavior를 작은 named interface로 받는다.

7. 코드 해부

SPEC

append 전후 len/cap와 address를 기록해 어떤 write가 original을 바꾸었는지 추적한다. address는 관찰 도구일 뿐 growth rule이 아니다.

SPEC

map은 concurrent write를 허용한다고 명시하지 않는다. 동시 접근의 correctness는 memory model과 synchronization으로 판단한다.

SPEC

generic constraint는 허용 type set과 operation을 정한다. generics는 runtime validation이나 semantic interface를 자동 제공하지 않는다.

8. 호출·goroutine·memory trace

VERIFIED BEHAVIOR

요청 body []byte의 allocation, validation copy, JSON string/rune 변환과 queue 전달을 ownership 표로 그린다.

PROJECT POLICY

trace 표는 owner, mutation 권한, lifetime, synchronization edge를 각 값마다 표시한다.

RECOMMENDED PRACTICE

Unicode validation은 byte length, rune count, grapheme/user-visible character 제한을 구분한다.

9. 실패 주입

PROJECT POLICY

nil interface, slice backing array 공유 버그와 concurrent map write를 각각 별도 subprocess에서 재현한다.

PROJECT POLICY

concurrent map write runtime fatal에 의존해 race absence를 증명하지 않는다. go test -race가 정식 검증 경로다.

RECOMMENDED PRACTICE

panic/recover 실습은 goroutine 경계를 포함한다. recover는 같은 goroutine의 deferred function에서만 효과가 있다.

10. 테스트

PROJECT POLICY

capacity가 남는/남지 않는 두 경우, multi-byte UTF-8, nil/empty slice, T/*T interface 만족을 table test로 만든다.

RECOMMENDED PRACTICE

map order를 assert하지 말고 key/value set을 비교한다.

PROJECT POLICY

panic test는 panic value와 resource cleanup을 함께 검증하며 정상 API 흐름에는 recover를 쓰지 않는다.

11. 성능

RECOMMENDED PRACTICE

copy 감소가 ownership 모호성·race 위험보다 가치 있는지 benchmark와 profile로 판단한다.

VERIFIED BEHAVIOR

string↔[]byte conversion은 일반적으로 data copy를 요구할 수 있으나 compiler 최적화가 일부 context에서 다를 수 있다.

PROJECT POLICY

unsafe zero-copy 변환은 capstone에서 금지한다.

12. 보안

RECOMMENDED PRACTICE

slice capacity를 그대로 신뢰하면 큰 backing array를 작은 view가 붙잡아 memory retention DoS를 만들 수 있다.

PROJECT POLICY

외부 입력은 byte limit 후 decode하고 tenant/provider credential을 fmt나 panic value에 포함하지 않는다.

RECOMMENDED PRACTICE

embedding과 promoted method가 의도치 않게 권한 있는 method를 public API에 노출하는지 검토한다.

13. 운영

RECOMMENDED PRACTICE

allocation regression, retained heap, panic count를 release 전후 비교하고 panic은 request boundary에서 격리하되 process invariant 위반은 숨기지 않는다.

PROJECT POLICY

typed nil은 lint와 test로 방지하고 error-returning constructor는 concrete nil을 직접 error로 반환하지 않는다.

14. 산출물

PROJECT POLICY

aliasing test, typed-nil test, method-set compile assertion, Unicode table test와 ownership diagram을 제출한다.

PROJECT POLICY

artifact는 lab/language와 lab/failures에 위치한다.

15. 완료 조건

PROJECT POLICY

value/pointer, array/slice/map/string/rune, struct/embedding, method set/receiver, interface nil, generics, defer/panic/recover를 production 예제로 설명하고 세 강제 실패를 재현·수정하면 완료다.

PROJECT POLICY

go test -race에서 alias fix가 통과해야 function verification이다.

16. 자가시험

SPEC

질문: append는 항상 새 array를 만드는가? (*T)(nil)을 error에 넣으면 nil인가? value receiver method는 *T에서도 호출 가능한가?

SPEC

method set 규칙과 addressability convenience를 interface satisfaction과 분리해 답한다.

자가시험 힌트

아니오, 아니오, 예. 단, 마지막의 호출 가능성과 interface method set은 같은 질문이 아니다.

P02P02 · Module과 packagedependency graph와 package boundary를 재현 가능한 build·clean install 관점에서 설계한다.16 sections#p02

학습 목표

  • go.mod, MVS, workspace와 package visibility를 읽는다.
  • replace, vendoring, generation과 build tag의 공급망 경계를 검증한다.

필수 주제

go.mod와 version selectionpackage boundary와 internalworkspacedependency와 replace 사용 위험vendoring과 reproducible buildcode generation과 build tag

직접 만들 산출물

  • go.mod
  • go.sum
  • lab/modules

1. 실체와 오해

SPEC

go.mod는 모든 transitive source를 복사한 lockfile이 아니다. module graph와 selected version을 해석하는 입력이다.

SPEC

Go module graph는 최소 버전 선택(MVS) 규칙으로 build list를 정한다. 항상 최신이나 일반 semver SAT solver와 같지 않다.

VERIFIED BEHAVIOR

go.sum은 다운로드 content 인증에 쓰이는 checksum을 기록하지만 dependency 신뢰성·취약성·license를 보증하지 않는다.

2. 선수 지식

RECOMMENDED PRACTICE

import path, semantic version, module proxy/checksum database와 filesystem path를 구분한다.

PROJECT POLICY

clean install은 개인 GOPATH, 상위 go.work, local replace에 의존하지 않아야 한다.

3. 15분 개념

SPEC

module은 versioned package collection이고 package는 같은 directory의 함께 빌드되는 Go source 집합이다.

internal 아래 package는 정해진 ancestor tree 안의 importer만 import할 수 있다. go.work는 여러 module을 local workspace build list로 묶는다.

SPEC

build constraints는 파일이 특정 build에 포함되는지 결정하며 파일명 GOOS/GOARCH suffix도 선택에 관여한다.

RECOMMENDED PRACTICE

package boundary는 change reason과 dependency direction으로 정하고 util dumping ground를 피한다.

4. runtime 내부

VERIFIED BEHAVIOR

go list -m all은 현재 module graph의 selected build list를, go mod graph는 requirement edge를 보여준다.

SPEC

replace directive는 module path/version의 source를 다른 module 또는 local directory로 바꾸지만 교체 대상 자체에 version을 붙이는 것은 아니다.

VERIFIED BEHAVIOR

local replace는 proxy/checksum 검증 경로 밖의 filesystem을 사용하므로 CI·consumer에서 재현되지 않을 수 있다.

5. 최소 코드

PROJECT POLICY

root module에서 selected dependency와 build provenance를 출력한다.

PROJECT POLICY

go.mod와 go.sum을 commit하고 go mod tidy 뒤 diff가 없어야 한다.

# macOS/Linux/PowerShell: same Go commands
go env GOWORK GOPROXY GOSUMDB
go list -m all
go mod graph
go mod verify
go version -m ./bin/notifier

6. production 확장

RECOMMENDED PRACTICE

cmd/notifier는 wiring만, internal/httpapi·store·worker·provider는 각 boundary와 test seam을 소유한다.

PROJECT POLICY

production build는 local replace를 허용하지 않고 module download, verify, test, build를 빈 cache에서도 실행한다.

RECOMMENDED PRACTICE

vendor를 택하면 vendor/modules.txt와 source를 함께 갱신하고 -mod=vendor를 CI에서 강제한다. vendor 사용 자체가 필수는 아니다.

7. 코드 해부

VERIFIED BEHAVIOR

go mod why, go mod graph와 go list -deps -json으로 예상치 못한 transitive dependency가 어떤 import에서 왔는지 찾는다.

RECOMMENDED PRACTICE

generated file에는 generator, exact invocation, generated marker와 review 가능한 diff를 남긴다.

PROJECT POLICY

go generate는 build/test에 자동 실행되지 않는다는 전제에서 generated output freshness를 별도 check한다.

8. 호출·goroutine·memory trace

VERIFIED BEHAVIOR

source import → package loader → module graph/version → module cache/vendor → compile cache → link의 artifact lineage를 그린다.

PROJECT POLICY

lineage에는 module@version, checksum, generator version, GOOS/GOARCH, build tags와 VCS revision을 포함한다.

9. 실패 주입

PROJECT POLICY

임시 local replace, stale generated file, 빠진 build-tag implementation, network-disabled empty cache를 각각 CI sandbox에서 주입한다.

PROJECT POLICY

개발자의 상위 go.work가 build를 바꾸지 않도록 release check는 GOWORK=off를 사용한다.

RECOMMENDED PRACTICE

offline build 요구가 있으면 vendor 또는 사내 proxy/cache를 명시적으로 운영하고 인터넷 없이 우연히 cache hit한 것을 재현성으로 부르지 않는다.

10. 테스트

PROJECT POLICY

go mod tidy/verify, go list, generated diff, platform build matrix와 clean cache build를 자동화한다.

PROJECT POLICY

macOS와 Windows 대상은 최소 GOOS=darwin 및 GOOS=windows cross-build로 compile boundary를 검사하고, OS별 실행 검증은 실제 runner로 구분해 기록한다.

RECOMMENDED PRACTICE

cross-compile 성공은 target OS runtime behavior 검증이 아니다.

11. 성능

RECOMMENDED PRACTICE

module 수나 package 수 자체보다 incremental compile cache hit, binary size, cold build duration을 측정한다.

PROJECT POLICY

dependency 추가는 binary/startup/build 영향과 maintenance ownership을 함께 review한다.

12. 보안

RECOMMENDED PRACTICE

checksum은 integrity 한 축일 뿐이다. provenance, vulnerability, license, maintainer risk와 generated tool binary를 따로 점검한다.

PROJECT POLICY

replace/exclude/retract 관련 변경은 security review 항목이며 private module credential을 go.mod나 로그에 넣지 않는다.

13. 운영

PROJECT POLICY

release artifact에서 go version -m 결과, SBOM/모듈 목록과 source commit을 보관해 rollback 대상을 식별한다.

RECOMMENDED PRACTICE

dependency upgrade는 canary와 rollback plan을 가진 작은 batch로 수행한다.

14. 산출물

PROJECT POLICY

go.mod, go.sum, module graph, package boundary diagram, clean-build log, generated freshness check와 platform build matrix를 제출한다.

PROJECT POLICY

중앙 artifact path는 go.mod, go.sum, lab/modules다.

15. 완료 조건

PROJECT POLICY

MVS와 package/internal/workspace 경계를 설명하고 replace·vendor·generation·build tag 실패를 clean install에서 검출하면 완료다.

PROJECT POLICY

darwin/windows compile과 실제 지원 OS runner 결과를 서로 다른 verification level로 표시한다.

16. 자가시험

SPEC

질문: go.sum이 모든 dependency를 lock하는가? go.work가 release consumer에게 자동 배포되는가? local replace가 checksum DB로 인증되는가?

SPEC

module graph 선택과 content checksum을 분리해 설명한다.

자가시험 힌트

모두 아니다. selected build list, workspace context, local filesystem source라는 서로 다른 경계다.

P03P03 · Error오류 identity, context, API contract와 retry 결정을 분리해 실패를 데이터로 다룬다.16 sections#p03

학습 목표

  • sentinel·typed·wrapped error를 errors.Is/As로 판별한다.
  • 내부 원인과 외부 API contract, retryability와 panic boundary를 분리한다.

필수 주제

explicit error, sentinel, typed errorwrapping, errors.Is/Asstack/contextAPI error contractretryable/non-retryablepanic boundary와 recover를 정상 흐름으로 쓰지 않는 이유

직접 만들 산출물

  • internal/apperr
  • internal/httpapi
  • lab/failures

1. 실체와 오해

SPEC

error 문자열은 identity가 아니다. wrapping chain과 type/sentinel contract가 machine decision을 지탱한다.

SPEC

error는 Error() string method를 가진 interface다. nil error는 성공 convention이지만 모든 non-nil error가 같은 정책을 뜻하지 않는다.

RECOMMENDED PRACTICE

문자열 비교나 substring으로 retry 여부를 정하지 않는다.

2. 선수 지식

RECOMMENDED PRACTICE

interface, nil, defer, HTTP status와 distributed failure의 unknown outcome을 복습한다.

PROJECT POLICY

학습자는 error identity, user message, log context, metric label을 별도 칸으로 설계한다.

3. 15분 개념

SPEC

sentinel은 package가 공개한 비교 가능한 identity, typed error는 구조화 field, wrapping은 cause chain과 추가 context를 제공한다.

errors.Is는 chain의 identity를, errors.As는 assignable type을 찾는다.

SPEC

fmt.Errorf의 %w와 Unwrap method는 error chain을 구성한다. wrapping은 public API에 underlying identity를 노출할 수 있다.

RECOMMENDED PRACTICE

추가 context에는 operation과 stable identifier를 넣되 payload나 secret을 넣지 않는다.

4. runtime 내부

VERIFIED BEHAVIOR

표준 error 값에는 자동 stack trace가 없다. 필요한 stack은 관측 계층에서 한 번 수집하거나 trace span/event와 결합한다.

SPEC

errors.Is/As는 custom Is/As와 Unwrap(error 또는 []error)를 따라갈 수 있다. chain traversal을 고려해 custom method를 작고 deterministic하게 유지한다.

RECOMMENDED PRACTICE

같은 error를 여러 layer에서 반복 log하지 말고 request/job boundary에서 한 번 기록한다.

5. 최소 코드

SPEC

provider 오류를 domain retry decision으로 번역하되 원인을 보존한다.

PROJECT POLICY

retry 분류는 typed field이며 HTTP status 문자열 parsing으로 구현하지 않는다.

type DeliveryError struct {
    Provider string
    Retryable bool
    Err error
}
func (e *DeliveryError) Error() string { return "deliver via " + e.Provider + ": " + e.Err.Error() }
func (e *DeliveryError) Unwrap() error { return e.Err }

func shouldRetry(err error) bool {
    var delivery *DeliveryError
    return errors.As(err, &delivery) && delivery.Retryable
}

6. production 확장

RECOMMENDED PRACTICE

store의 duplicate key, context cancellation, provider 4xx/5xx/timeout을 domain code와 retry policy로 변환하고 HTTP response는 안정된 contract만 노출한다.

PROJECT POLICY

API error body는 code, safe message, request_id를 제공하고 internal chain·SQL·provider credential은 노출하지 않는다.

PROJECT POLICY

context.Canceled와 DeadlineExceeded는 cause와 side-effect stage를 함께 보아 retry 여부를 정한다.

7. 코드 해부

RECOMMENDED PRACTICE

handler→service→store/provider chain에서 어느 layer가 identity를 만들고, 어느 layer가 context를 더하고, 어느 boundary가 response/log로 바꾸는지 표시한다.

RECOMMENDED PRACTICE

낮은 layer가 HTTP status를 반환하거나 handler가 driver error string을 해석하면 boundary가 누출된 것이다.

PROJECT POLICY

같은 operation에서 error를 %v로 잃거나 %w로 의도치 않게 public contract화하지 않도록 test한다.

8. 호출·goroutine·memory trace

PROJECT POLICY

DB insert 실패, provider timeout, retry exhaustion을 cause chain, span status, log event, API/job state로 나란히 추적한다.

PROJECT POLICY

error metric label에는 bounded code만 쓰고 raw message, tenant ID, request ID를 label로 쓰지 않는다.

RECOMMENDED PRACTICE

stack은 error마다 누적하지 말고 diagnostic value가 있는 경계에서 sampling한다.

9. 실패 주입

PROJECT POLICY

provider가 timeout, 429, 400, connection reset과 response-after-commit unknown outcome을 반환하게 한다.

PROJECT POLICY

각 failure는 retryable/non-retryable/unknown으로 기대 분류하고 state transition을 assert한다.

RECOMMENDED PRACTICE

panic injection은 handler/worker boundary recovery를 검증하되 recover를 domain error branch로 사용하지 않는다.

10. 테스트

PROJECT POLICY

errors.Is/As, multi-wrap, typed nil 방지, stable API JSON, retry matrix와 panic cleanup을 table-driven test로 검증한다.

PROJECT POLICY

error test는 full string보다 identity와 structured field를 우선 assert한다.

RECOMMENDED PRACTICE

public error text가 contract라면 golden보다 명시적 code와 schema test를 선호한다.

11. 성능

RECOMMENDED PRACTICE

error path allocation은 실제 error rate와 결합해 측정한다. success hot path를 stack capture로 오염시키지 않는다.

VERIFIED BEHAVIOR

fmt formatting, wrapping과 stack collection은 비용이 있으나 bottleneck 여부는 workload profile로만 판단한다.

12. 보안

PROJECT POLICY

tenant isolation 실패, credential, SQL, provider response body는 public error와 unsanitized log에 넣지 않는다.

RECOMMENDED PRACTICE

공격자가 만든 high-cardinality message를 metric label로 쓰면 비용·가용성 공격이 된다.

PROJECT POLICY

panic response는 generic 500이며 request ID만 연결한다.

13. 운영

RECOMMENDED PRACTICE

retryable rate, permanent failure rate, unknown outcome, panic recovery와 top bounded error codes를 dashboard/runbook에 연결한다.

PROJECT POLICY

새 error code는 API compatibility와 alert routing review를 거친다.

14. 산출물

PROJECT POLICY

error taxonomy, API error schema, provider failure matrix, Is/As tests와 panic boundary test를 제출한다.

PROJECT POLICY

artifact 경로는 internal/apperr, internal/httpapi, lab/failures다.

15. 완료 조건

PROJECT POLICY

sentinel·typed·wrap·Is/As를 설명하고 stack/context, API contract, retry 분류, panic boundary를 실제 state transition test로 검증하면 완료다.

PROJECT POLICY

recover가 정상 흐름에 없는지 source audit로 확인한다.

16. 자가시험

SPEC

질문: %w는 언제 사용해야 하는가? timeout이면 항상 retry 가능한가? recover가 다른 goroutine의 panic을 잡는가?

RECOMMENDED PRACTICE

identity 공개 의도, side-effect stage/idempotency, goroutine-local unwind라는 세 축으로 답한다.

자가시험 힌트

cause를 contract로 보존할 때만 %w, timeout은 unknown outcome일 수 있으며, recover는 다른 goroutine panic을 잡지 못한다.

P04P04 · Concurrencygoroutine 수가 아니라 ownership, bound와 happens-before edge로 concurrency를 설계한다.16 sections#p04

학습 목표

  • channel·lock·atomic의 synchronization contract를 설명한다.
  • bounded worker pool에서 race, deadlock, close panic을 재현하고 제거한다.

필수 주제

goroutineunbuffered/buffered channel과 selectchannel ownership과 close 규칙worker pool, fan-in/fan-out, bounded concurrency, semaphoresync.WaitGroup, Mutex/RWMutex, atomicdata race, deadlock, Go memory model

직접 만들 산출물

  • internal/worker
  • lab/failures
  • profiles

1. 실체와 오해

SPEC

channel을 쓴다고 race-free가 되지 않고, race-free라고 deadlock-free도 아니다.

SPEC

동시에 같은 location을 접근하며 하나 이상이 write이고 synchronization이 없으면 data race다. race-free program은 Go memory model의 DRF-SC 보장을 받는다.

RECOMMENDED PRACTICE

goroutine마다 lifetime, owner, upper bound와 종료 신호를 설계 전에 적는다.

2. 선수 지식

RECOMMENDED PRACTICE

call stack, blocking, context cancellation, invariant와 critical section을 복습한다.

PROJECT POLICY

sleep으로 ordering을 만드는 test는 deterministic concurrency test로 인정하지 않는다.

3. 15분 개념

SPEC

unbuffered send는 대응 receive와 만나 진행한다. buffered channel은 capacity까지 send/receive를 분리하지만 queue ownership 문제를 없애지 않는다.

select는 진행 가능한 case 중 하나를 선택하고 default가 있으면 blocking하지 않을 수 있다.

SPEC

closed channel로 send하면 panic이고 closed channel receive는 buffer를 소진한 뒤 zero value와 ok=false를 돌려준다. nil channel operation은 영원히 block한다.

RECOMMENDED PRACTICE

보통 send side가 channel을 닫고 receiver는 닫지 않는다. 여러 sender가 있으면 lifecycle owner 한 곳이 close를 조정한다.

4. runtime 내부

VERIFIED BEHAVIOR

channel과 mutex 구현 세부는 release에 따라 바뀔 수 있다. correctness는 표준 synchronization happens-before guarantee에만 세운다.

SPEC

channel send는 대응 receive completion보다 먼저 synchronized되고 close는 zero-value receive보다 먼저 synchronized된다. mutex unlock과 이후 lock 사이에도 documented edge가 있다.

SPEC

sync/atomic operation은 documented atomic semantics를 제공하지만 여러 field invariant를 자동 원자화하지 않는다.

5. 최소 코드

RECOMMENDED PRACTICE

fixed worker 수와 한 명의 queue owner가 enqueue·close·wait 순서를 관리한다.

PROJECT POLICY

worker count와 queue capacity는 config에 bound되고 enqueue는 context cancellation을 선택한다.

func run(ctx context.Context, workers int, jobs <-chan Job, handle func(context.Context, Job)) {
    var wg sync.WaitGroup
    wg.Add(workers)
    for i := 0; i < workers; i++ {
        go func() {
            defer wg.Done()
            for {
                select {
                case <-ctx.Done(): return
                case job, ok := <-jobs:
                    if !ok { return }
                    handle(ctx, job)
                }
            }
        }()
    }
    wg.Wait()
}

6. production 확장

RECOMMENDED PRACTICE

DB에서 claim한 jobs를 bounded fan-out하고 결과를 fan-in해 state update한다. provider별 semaphore로 외부 concurrency도 제한한다.

PROJECT POLICY

queue full 정책은 block-with-deadline 또는 reject이며 무제한 goroutine spill은 금지한다.

RECOMMENDED PRACTICE

RWMutex는 read가 많다는 인상으로 고르지 말고 contention profile과 invariant 단순성을 비교한다.

7. 코드 해부

PROJECT POLICY

job lifecycle의 mutable state를 channel owner, mutex-protected state, DB truth 중 정확히 하나의 authority에 배정한다.

RECOMMENDED PRACTICE

WaitGroup Add는 goroutine 시작 전에 하고 worker가 Done을 defer한다. 새 WaitGroup.Go API가 사용 가능한 version이면 그 documented contract를 따르되 version floor를 명시한다.

PROJECT POLICY

atomic counter는 metric처럼 독립된 scalar에만 사용하고 job state machine에는 mutex/DB transaction을 쓴다.

8. 호출·goroutine·memory trace

SPEC

accept → handler G → DB → queue send → worker G → provider → result channel의 goroutine과 memory ownership을 그린다.

PROJECT POLICY

각 arrow는 call, data copy, channel synchronization, lock edge, DB durability 중 무엇인지 표시한다.

RECOMMENDED PRACTICE

buffer size를 correctness edge로 사용하지 않는다. capacity 변경에도 invariant가 유지되어야 한다.

9. 실패 주입

PROJECT POLICY

goroutine leak, channel close panic, concurrent map write와 deadlock을 timeout/subprocess로 격리해 재현한다.

PROJECT POLICY

panic/fatal 실습은 정상 suite process를 죽이지 않으며 helper subprocess exit와 stderr를 assert한다.

PROJECT POLICY

race 실습은 race build tag로 격리하고 go test -race -tags=racefail에서 expected detection을 확인한다.

10. 테스트

PROJECT POLICY

barrier channel, fake handler와 explicit acknowledgement로 exact interleaving을 만들고 worker 종료와 no-send-after-close를 assert한다.

RECOMMENDED PRACTICE

race detector는 실행된 path의 race만 찾는다. coverage와 adversarial schedules를 함께 늘린다.

PROJECT POLICY

deadlock test는 짧은 local timeout과 diagnostic goroutine dump를 남긴다.

11. 성능

RECOMMENDED PRACTICE

worker 수를 CPU 수에 기계적으로 맞추지 말고 provider/DB latency, rate limit, queue wait와 saturation으로 조정한다.

PROJECT POLICY

mutex/block profile, execution trace와 load test를 함께 사용해 contention을 확인한다.

RECOMMENDED PRACTICE

larger buffer는 backpressure를 지연시킬 뿐 capacity를 만들지 않는다.

12. 보안

RECOMMENDED PRACTICE

unbounded goroutine·queue와 tenant 간 공용 semaphore는 resource exhaustion 및 noisy-neighbor 경로다.

PROJECT POLICY

global bound 안에서 tenant별 fairness/rate bound를 두고 credential-bearing Job의 dump/log를 redact한다.

13. 운영

PROJECT POLICY

queue depth/age, active workers, enqueue wait, provider semaphore wait, goroutine count와 mutex/block time을 운영한다.

RECOMMENDED PRACTICE

goroutine count 증가만으로 leak을 단정하지 말고 workload-normalized trend와 dump stack signature를 확인한다.

14. 산출물

PROJECT POLICY

bounded pool, ownership diagram, deterministic test, race report, deadlock dump, mutex/block profile을 제출한다.

PROJECT POLICY

artifact 경로는 internal/worker, lab/failures, profiles다.

15. 완료 조건

PROJECT POLICY

channel/close/select/worker/fan/semaphore/WaitGroup/locks/atomic을 memory-model edge로 설명하고 leak·close panic·map race·deadlock을 재현 후 제거하면 완료다.

PROJECT POLICY

go test와 go test -race 통과는 function 검증이며 실제 saturation UX는 별도 product 검증이다.

16. 자가시험

SPEC

질문: buffered send가 즉시 끝나면 receiver가 write를 이미 보았는가? channel을 누가 닫아야 하는가? race-free면 deadlock-free인가?

SPEC

synchronization edge, ownership policy와 liveness는 서로 다른 질문이다.

자가시험 힌트

첫째는 대응 receive 전이므로 아니다. 둘째는 lifecycle을 아는 send-side owner, 셋째도 아니다.

P05P05 · Context와 cancellation요청 lifetime을 DB·HTTP·goroutine까지 전달하고 의도적 background 분리를 명시한다.16 sections#p05

학습 목표

  • context tree, deadline과 cancellation propagation을 코드로 추적한다.
  • client disconnect·cleanup·detached work에서 leak 없는 lifetime을 설계한다.

필수 주제

context tree, deadline, timeoutcancellation propagationvalue 오용DB/HTTP 호출 전달detached background workclient disconnect, goroutine leak, cleanup

직접 만들 산출물

  • internal/platform/contextcheck
  • internal/httpapi
  • lab/failures

1. 실체와 오해

SPEC

context는 취소 가능한 모든 작업을 자동 중단하지 않는다. callee가 Done, Err 또는 context-aware API를 실제로 관찰해야 한다.

SPEC

parent가 취소되면 derived child도 취소된다. child 취소가 parent를 취소하지는 않는다.

RECOMMENDED PRACTICE

context를 optional-parameter bag이나 dependency container로 사용하지 않는다.

2. 선수 지식

RECOMMENDED PRACTICE

goroutine lifecycle, select, HTTP request, database/sql Context API와 idempotency를 복습한다.

PROJECT POLICY

context는 첫 parameter ctx로 전달하고 struct field에 장기 저장하지 않는다.

3. 15분 개념

SPEC

WithCancel/WithDeadline/WithTimeout은 parent를 가리키는 child와 cancel function을 만든다. cancel 호출은 timer와 parent reference 자원을 해제한다.

Value는 API/process를 가로지르는 request-scoped metadata용이며 business argument용이 아니다.

SPEC

Context는 여러 goroutine에서 동시에 사용할 수 있고 nil Context 대신 TODO 또는 Background를 사용한다.

RECOMMENDED PRACTICE

deadline은 downstream 호출마다 더 길게 늘리지 말고 남은 budget에서 connect/read/processing budget을 배분한다.

4. runtime 내부

VERIFIED BEHAVIOR

표준 context 구현은 cancellation tree와 Done channel/timer를 관리하지만 concrete type이나 internal field에 의존하면 안 된다.

SPEC

CancelFunc를 호출하지 않으면 parent가 취소될 때까지 child와 관련 resource가 남을 수 있고 go vet이 일부 경로의 누락을 검사한다.

SPEC

WithoutCancel은 parent value를 보되 deadline, Err와 cancellation을 상속하지 않는 Context를 만든다. 이는 지원 Go version에 따라 사용 가능하다.

5. 최소 코드

RECOMMENDED PRACTICE

DB와 outbound HTTP에 같은 request context를 전달하고 모든 derived timeout을 defer cancel한다.

PROJECT POLICY

provider request는 NewRequestWithContext를 사용하며 default context.Background로 request cancellation을 잃지 않는다.

func deliver(ctx context.Context, db *sql.DB, client *http.Client, id string) error {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    if _, err := db.ExecContext(ctx, "UPDATE jobs SET state=? WHERE id=?", "sending", id); err != nil {
        return fmt.Errorf("mark sending: %w", err)
    }
    req, err := http.NewRequestWithContext(ctx, http.MethodPost, providerURL, nil)
    if err != nil { return err }
    resp, err := client.Do(req)
    if err != nil { return fmt.Errorf("provider: %w", err) }
    defer resp.Body.Close()
    return nil
}

6. production 확장

RECOMMENDED PRACTICE

HTTP request는 DB에 durable job을 commit할 때까지만 소유한다. commit 뒤 worker 처리는 process lifecycle context와 job deadline을 사용한다.

PROJECT POLICY

fire-and-forget goroutine 대신 durable queue/DB를 background handoff 경계로 사용한다.

PROJECT POLICY

의도적으로 detached한 짧은 telemetry cleanup은 WithoutCancel 또는 새 bounded context로 명시하고 자체 timeout과 owner를 둔다.

7. 코드 해부

PROJECT POLICY

handler→service→store/provider 모든 signature에서 ctx가 첫 parameter인지, context-aware method를 호출하는지 추적한다.

RECOMMENDED PRACTICE

Context value key는 package-private comparable type으로 충돌을 막고 request ID·trace context 같은 metadata만 저장한다.

PROJECT POLICY

tenant ID는 authorization argument로 명시 전달하고 Context value만 신뢰하지 않는다.

8. 호출·goroutine·memory trace

SPEC

server root → request context → DB/provider timeout child와 별도의 process root → worker job child를 tree로 그린다.

PROJECT POLICY

각 node는 owner, deadline, cancel caller, cleanup과 side-effect boundary를 표시한다.

RECOMMENDED PRACTICE

trace span propagation과 cancellation propagation은 같은 Context를 쓸 수 있지만 의미가 같지는 않다.

9. 실패 주입

PROJECT POLICY

context 취소 미전파와 goroutine leak을, client connection close 후 provider가 계속 block하는 broken implementation으로 재현한다.

PROJECT POLICY

broken path는 build tag로 격리하고 goroutine dump에서 blocking stack signature와 deadline 초과를 assert한다.

RECOMMENDED PRACTICE

고친 path는 cancellation latency upper bound와 resource cleanup을 검증한다.

10. 테스트

PROJECT POLICY

already-canceled, deadline expiry, parent cancel, client disconnect, detached cleanup과 blocked enqueue를 fake clock/barrier로 test한다.

RECOMMENDED PRACTICE

time.Sleep 대신 test가 clock advance와 cancellation acknowledgement를 직접 제어한다.

PROJECT POLICY

go vet의 lostcancel 진단과 leak test를 함께 실행한다.

11. 성능

RECOMMENDED PRACTICE

짧은 nested timeout과 per-item timer 폭증을 profile하고 batch/shared scheduling 대안을 측정한다.

VERIFIED BEHAVIOR

Context lookup은 parent chain을 걸을 수 있으므로 hot-path data store로 사용하지 않는다.

PROJECT POLICY

성능을 이유로 cancellation check를 제거하지 않는다. profiling evidence와 safe alternative가 필요하다.

12. 보안

PROJECT POLICY

deadline과 body/provider limit은 slow-client·slow-provider resource exhaustion 방어의 일부다.

RECOMMENDED PRACTICE

Context value에 credential이나 mutable authorization object를 저장하지 않는다.

PROJECT POLICY

background detach는 tenant authorization scope를 복사하지 않고 durable job에서 다시 load/validate한다.

13. 운영

RECOMMENDED PRACTICE

canceled/deadline 비율을 operation과 stage별 bounded label로 보고, client-canceled와 server-timeout을 구분한다.

PROJECT POLICY

runbook은 goroutine dump에서 context 미전파 stack과 provider timeout stack을 구분하는 절차를 포함한다.

14. 산출물

PROJECT POLICY

context tree, propagation test, client-disconnect integration test, broken/fixed leak dump와 lostcancel check를 제출한다.

PROJECT POLICY

artifact 경로는 internal/platform/contextcheck, internal/httpapi, lab/failures다.

15. 완료 조건

PROJECT POLICY

tree/deadline/timeout/value/DB·HTTP propagation/detach/disconnect/leak/cleanup을 설명하고 두 강제 failure를 재현·수정하면 완료다.

PROJECT POLICY

function 검증은 cancellation test, quality 검증은 bounded latency와 no-leak evidence, product 검증은 사용자 실습 후로 분리한다.

16. 자가시험

SPEC

질문: 요청 context를 worker에 그대로 저장해도 되는가? CancelFunc를 생략해도 deadline이 끝나면 항상 무해한가? WithoutCancel에는 Done이 있는가?

SPEC

lifetime ownership, 조기 resource release와 detached semantics로 답한다.

자가시험 힌트

아니오, 아니오, 아니오(nil Done). worker는 process/job context를 사용하고 cancel은 가능한 빨리 호출한다.

P06P06 · HTTPnet/http의 connection·request lifetime, timeout와 재사용 규칙을 안전한 notification API로 연결한다.16 sections#p06

학습 목표

  • Server·handler·middleware와 connection/request goroutine 동작을 보장 수준별로 설명한다.
  • bounded input, idempotency, client Transport와 graceful shutdown을 검증한다.

필수 주제

net/http server, accept, handler, middlewaregoroutine per connection/request 공식 구현 검증body limit, validationserver timeout, client timeout, Transportconnection reuse와 response body closeidempotency와 graceful shutdown

직접 만들 산출물

  • internal/httpapi
  • internal/provider
  • integration

1. 실체와 오해

VERIFIED BEHAVIOR

net/http를 request마다 무조건 새 goroutine 하나라고 요약하면 protocol과 implementation 차이를 숨긴다.

VERIFIED BEHAVIOR

공식 Server.Serve 문서는 accepted connection마다 service goroutine을 만든다고 명시한다.

VERIFIED BEHAVIOR

현재 표준 구현에서 HTTP/1.x handler는 connection service loop에서 실행되는 반면 HTTP/2는 stream/request 처리가 다른 concurrency 구조를 쓴다. 정확한 내부 goroutine 수는 API contract가 아니다.

2. 선수 지식

RECOMMENDED PRACTICE

TCP connection, HTTP framing, context, io.Reader, JSON과 idempotency key를 복습한다.

PROJECT POLICY

Server와 Client 모두 zero-value default에 운영 요구를 맡기지 않고 explicit timeout/Transport를 구성한다.

3. 15분 개념

SPEC

Server는 listener에서 accept하고 Handler가 ResponseWriter와 Request를 통해 response를 만든다. middleware는 Handler를 감싸 cross-cutting policy를 적용한다.

Request.Context는 client connection close, HTTP/2 cancellation 또는 ServeHTTP 반환에 따라 취소될 수 있다.

SPEC

Request body는 stream이며 한 번 소비된다. MaxBytesReader 또는 LimitReader와 decoder validation 순서를 명시한다.

RECOMMENDED PRACTICE

middleware 순서는 recovery→request ID/trace→access log→auth/tenant→limit→handler처럼 실패 관측과 보안 의미를 검토해 정한다.

4. runtime 내부

VERIFIED BEHAVIOR

HTTP/1 keep-alive는 한 connection에서 request를 이어 처리할 수 있고 HTTP/2는 multiplex한다. 따라서 connection 수, handler concurrency와 goroutine 수는 같지 않다.

VERIFIED BEHAVIOR

http.Transport는 connection pool과 reuse를 관리하며 concurrent use에 안전하도록 설계됐다. request마다 새 Transport를 만들면 pooling을 잃는다.

VERIFIED BEHAVIOR

response body를 닫지 않으면 resource와 connection reuse를 해칠 수 있다. HTTP/1 재사용은 body를 끝까지 읽는 조건에도 영향을 받는다.

5. 최소 코드

PROJECT POLICY

bounded JSON decode, stable validation error와 explicit Server timeout을 가진 create endpoint를 만든다.

PROJECT POLICY

Idempotency-Key와 authenticated tenant를 복합 uniqueness 경계로 사용하고 handler memory map이 아니라 DB에 저장한다.

srv := &http.Server{
    Addr:              ":8080",
    Handler:           api,
    ReadHeaderTimeout: 2 * time.Second,
    ReadTimeout:       5 * time.Second,
    WriteTimeout:      10 * time.Second,
    IdleTimeout:       60 * time.Second,
    MaxHeaderBytes:    1 << 20,
}

func decode(w http.ResponseWriter, r *http.Request, dst any) error {
    r.Body = http.MaxBytesReader(w, r.Body, 64<<10)
    dec := json.NewDecoder(r.Body)
    dec.DisallowUnknownFields()
    return dec.Decode(dst)
}

6. production 확장

RECOMMENDED PRACTICE

POST /v1/notifications는 새 resource commit 뒤 201 Created와 Location을, 같은 idempotency request replay에는 200 OK를 반환한다. GET은 tenant-scoped status를 제공한다.

PROJECT POLICY

201 Created/200 OK는 durable notification resource 생성·재사용을 뜻하며 provider delivery 성공을 뜻하지 않는다.

PROJECT POLICY

outbound client는 shared Transport, overall Client.Timeout 또는 context budget, connect/TLS/response-header/idle limits를 조합한다.

7. 코드 해부

VERIFIED BEHAVIOR

accept→connection service→read request→middleware→handler→transaction→response와 provider Client.Do→Transport→dial/reuse→body close를 두 흐름으로 해부한다.

RECOMMENDED PRACTICE

defer resp.Body.Close는 err 확인 뒤 즉시 둔다. status 검사 전에 제한된 body를 읽어 error context를 만들 수 있다.

PROJECT POLICY

provider error body와 header를 무제한 읽거나 그대로 log하지 않는다.

8. 호출·goroutine·memory trace

VERIFIED BEHAVIOR

connection ID와 request/trace ID를 분리하고 HTTP/1 keep-alive, HTTP/2 multiplex, handler goroutine, DB connection과 provider connection 관계를 표시한다.

PROJECT POLICY

protocol, Go version과 GODEBUG/HTTP2 설정을 trace evidence에 기록한다.

RECOMMENDED PRACTICE

distributed span은 handler와 outbound request를 연결하지만 runtime goroutine identity를 stable business key로 쓰지 않는다.

9. 실패 주입

PROJECT POLICY

HTTP body 미종료, slowloris header, oversized body, provider hang, client disconnect와 graceful shutdown timeout을 주입한다.

PROJECT POLICY

body-leak 실습은 repeated request 후 connection count/goroutine/FD 또는 Transport trace의 reuse 차이를 측정하고 response body를 항상 닫는 fix와 비교한다.

PROJECT POLICY

shutdown timeout은 stuck handler를 dump하고 hard-close 단계로 전환하는 expected policy를 검증한다.

10. 테스트

PROJECT POLICY

httptest unit, real listener integration, raw TCP timeout test와 idempotency concurrency test를 구분한다.

RECOMMENDED PRACTICE

ResponseRecorder만으로 connection reuse, disconnect와 server timeout을 검증했다고 주장하지 않는다.

PROJECT POLICY

same tenant/key concurrent POST는 하나의 durable notification ID를 반환해야 한다.

11. 성능

RECOMMENDED PRACTICE

throughput뿐 아니라 handler duration, request body size, Transport dial/reuse, connection pool wait와 allocation을 측정한다.

PROJECT POLICY

load test는 keep-alive on/off와 HTTP protocol을 기록하고 open-loop arrival rate로 overload를 드러낸다.

12. 보안

PROJECT POLICY

body/header limit, read header timeout, authentication·tenant authorization, TLS와 safe error response를 API boundary에 둔다.

RECOMMENDED PRACTICE

Idempotency-Key는 authentication이 아니며 tenant와 endpoint/payload fingerprint scope를 정한다.

PROJECT POLICY

redirect policy가 provider credential header를 다른 host로 전달하지 않도록 명시한다.

13. 운영

RECOMMENDED PRACTICE

in-flight, status class, timeout stage, request size, keep-alive/reuse, shutdown phase와 acceptance latency를 운영한다.

PROJECT POLICY

readiness를 먼저 내리고 listener shutdown→handler drain→worker drain 순서와 각 deadline을 runbook에 둔다.

14. 산출물

PROJECT POLICY

server/client config, handler/middleware, idempotency integration test, body-close trace, timeout matrix와 shutdown log를 제출한다.

PROJECT POLICY

artifact 경로는 internal/httpapi, internal/provider, integration이다.

15. 완료 조건

PROJECT POLICY

accept·goroutine nuance·handler/middleware·limits·timeouts·Transport/reuse/body close·idempotency·shutdown을 설명하고 두 강제 HTTP failure를 재현·수정하면 완료다.

PROJECT POLICY

connection-level behavior는 real listener evidence가 있어야 quality verification이다.

16. 자가시험

VERIFIED BEHAVIOR

질문: Server.Serve가 request마다 정확히 한 goroutine을 약속하는가? body Close만 하면 모든 response가 재사용 가능한가? WriteTimeout 하나로 provider 호출도 제한되는가?

VERIFIED BEHAVIOR

protocol implementation, body drain/framing, request context/client budget을 분리해 답한다.

자가시험 힌트

모두 아니다. connection service goroutine만 문서화되고, 재사용 조건은 더 있으며, outbound timeout은 별도다.

P07P07 · Databasedatabase/sql pool과 transaction을 tenant-safe durable job state machine의 경계로 사용한다.16 sections#p07

학습 목표

  • pool 설정·context·Rows lifetime과 connection leak을 관찰한다.
  • transaction/isolation/retry/migration을 idempotent notification 저장에 적용한다.

필수 주제

database/sql connection poolMaxOpen/Idle/Lifetimetransaction과 isolationprepared statement와 context cancellationscan, NULL, query iteration closeconnection leak, retryable transaction, migration

직접 만들 산출물

  • internal/store
  • migrations
  • integration

1. 실체와 오해

VERIFIED BEHAVIOR

sql.Open은 보통 즉시 network 연결 성공을 보장하지 않고 *sql.DB는 한 connection이 아니라 concurrent-safe pool handle이다.

SPEC

database/sql API contract와 실제 SQL/isolation/error semantics 사이에는 driver·database 경계가 있다.

RECOMMENDED PRACTICE

startup readiness가 DB를 요구하면 PingContext와 migration/version check를 explicit deadline으로 실행한다.

2. 선수 지식

RECOMMENDED PRACTICE

SQL constraint/index, ACID, isolation anomaly, context와 idempotency를 복습한다.

PROJECT POLICY

tenant_id는 모든 notification/job key와 query predicate의 일부이며 application filter만으로 isolation을 주장하지 않는다.

3. 15분 개념

VERIFIED BEHAVIOR

DB는 idle/in-use connection을 pool로 관리한다. MaxOpen은 total bound, MaxIdle은 idle retention, ConnMaxLifetime/IdleTime은 reuse 수명을 제한한다.

transaction은 하나의 connection에 묶인 atomic unit이며 commit 결과가 성공해야 durable transition을 확정할 수 있다.

VERIFIED BEHAVIOR

SetMaxOpenConns의 0 이하 값은 documented unlimited이고 MaxIdleConns default는 현재 구현 문서상 2이나 향후 바뀔 수 있다.

RECOMMENDED PRACTICE

pool bound는 instance 수×MaxOpen이 DB budget을 넘지 않게 정하고 대기 지표로 검증한다.

4. runtime 내부

VERIFIED BEHAVIOR

QueryContext는 pool에서 connection을 얻고 Rows가 닫히거나 소진될 때까지 보유할 수 있다. transaction도 Commit/Rollback 전까지 connection을 점유한다.

SPEC

Rows.Next iteration이 끝나면 Rows.Err를 확인하고 Rows를 닫는다. NULL은 sql.Null* 또는 nullable destination으로 명시한다.

VERIFIED BEHAVIOR

context 취소가 실제 query를 즉시 중단하는 정도는 driver/database 지원에도 달려 있다. cancellation 뒤 connection 상태는 driver가 관리한다.

5. 최소 코드

PROJECT POLICY

tenant와 idempotency key unique constraint 아래 notification과 job을 한 transaction에 저장한다.

PROJECT POLICY

defer Rollback을 먼저 두고 Commit 성공만 durable acceptance로 반환한다.

func (s *Store) Create(ctx context.Context, n Notification) (err error) {
    tx, err := s.db.BeginTx(ctx, &sql.TxOptions{})
    if err != nil { return fmt.Errorf("begin: %w", err) }
    defer tx.Rollback()

    if _, err = tx.ExecContext(ctx,
        "INSERT INTO notifications(tenant_id,id,idempotency_key,state) VALUES(?,?,?,?)",
        n.TenantID, n.ID, n.Key, "queued"); err != nil {
        return fmt.Errorf("insert notification: %w", err)
    }
    if _, err = tx.ExecContext(ctx,
        "INSERT INTO jobs(tenant_id,notification_id,state) VALUES(?,?,?)",
        n.TenantID, n.ID, "ready"); err != nil {
        return fmt.Errorf("insert job: %w", err)
    }
    return tx.Commit()
}

6. production 확장

RECOMMENDED PRACTICE

worker claim은 DB별 locking primitive와 lease/checkpoint로 경쟁 worker 간 중복 claim을 막고 crash recovery를 허용한다.

PROJECT POLICY

transaction 안에서 external provider를 호출하지 않는다. DB lock duration과 unknown outcome을 결합하지 않는다.

PROJECT POLICY

prepared statement는 실제 반복 query와 driver behavior를 기준으로 사용하며 global prepare가 모든 physical connection 하나만 준비한다고 가정하지 않는다.

7. 코드 해부

VERIFIED BEHAVIOR

HTTP insert, worker claim, delivery result, reconciliation query마다 pool checkout→query/tx→Rows/Commit→return 경로를 표시한다.

RECOMMENDED PRACTICE

QueryRow는 Scan에서 error를 표면화한다. Scan을 생략하면 no-row와 query failure를 잃는다.

PROJECT POLICY

query에는 tenant predicate와 stable ordering/pagination을 명시하고 SELECT *를 사용하지 않는다.

8. 호출·goroutine·memory trace

VERIFIED BEHAVIOR

handler/worker goroutine이 pool에서 wait→connection acquire→server execution→scan→release하는 시간을 span과 DBStats에 연결한다.

PROJECT POLICY

trace attribute에는 query operation/table만 넣고 raw SQL parameter나 tenant payload를 넣지 않는다.

RECOMMENDED PRACTICE

DBStats.WaitCount/WaitDuration 증가는 saturation 증거 후보지만 traffic와 query latency를 함께 보아야 한다.

9. 실패 주입

PROJECT POLICY

DB connection leak은 Rows.Close를 생략하고 small MaxOpen 아래 concurrent query를 막아 재현한다.

PROJECT POLICY

failure test는 pool wait timeout, InUse/Idle/WaitCount와 goroutine stack을 기록하고 fixed path가 bounded time에 회복됨을 assert한다.

RECOMMENDED PRACTICE

database restart, serialization failure, connection reset와 commit-response loss도 실제 dependency로 주입해 retry/unknown outcome을 구분한다.

10. 테스트

PROJECT POLICY

store unit은 SQL contract fake에 과도하게 의존하지 않고 실제 DB integration에서 migration, constraints, isolation과 cancellation을 검증한다.

PROJECT POLICY

retryable transaction test는 전체 closure를 새 transaction에서 다시 실행하고 external side effect가 없음을 확인한다.

RECOMMENDED PRACTICE

Testcontainers 또는 docker-compose DB를 쓸 때 image/version digest와 readiness를 고정한다.

11. 성능

RECOMMENDED PRACTICE

query latency를 pool wait, server execution, scan으로 나누고 execution plan/index와 batch size를 workload에서 측정한다.

PROJECT POLICY

MaxOpen 증가를 첫 해결책으로 쓰지 않는다. DB CPU/locks/connections와 application wait를 함께 본다.

RECOMMENDED PRACTICE

prepared statement는 benchmark와 database observation으로 효과를 확인한다.

12. 보안

PROJECT POLICY

parameterized query, least-privilege DB role, migration role 분리와 tenant predicate/constraint를 사용한다.

RECOMMENDED PRACTICE

dynamic identifier는 placeholder로 parameterize할 수 없으므로 allowlist로 구성한다.

PROJECT POLICY

DSN과 query parameter는 log/trace/profile metadata에서 redact한다.

13. 운영

RECOMMENDED PRACTICE

Open/InUse/Idle, WaitCount/Duration, max lifetime closes, transaction duration, slow query, deadlock/serialization code와 migration version을 운영한다.

PROJECT POLICY

migration은 backward-compatible expand→deploy→contract 단계, timeout/lock budget, backup/rollback 또는 forward-fix plan을 가진다.

14. 산출물

PROJECT POLICY

schema/migrations, pool config, transaction tests, NULL/Rows tests, connection-leak evidence와 query/runbook을 제출한다.

PROJECT POLICY

artifact 경로는 internal/store, migrations, integration이다.

15. 완료 조건

PROJECT POLICY

pool/limits/transaction/isolation/prepared/context/scan/NULL/Rows/leak/retry/migration을 설명하고 leak과 restart failure를 실제 dependency에서 검증하면 완료다.

PROJECT POLICY

mock 통과만으로 DB quality verification을 주장하지 않는다.

16. 자가시험

VERIFIED BEHAVIOR

질문: sql.Open 성공이면 DB가 reachable한가? Rows가 scope를 벗어나면 즉시 connection이 반환되는가? serialization retry에서 기존 Tx를 재사용하는가?

RECOMMENDED PRACTICE

lazy open, explicit Rows lifecycle와 fresh transaction closure로 답한다.

자가시험 힌트

모두 아니다. PingContext가 별도이고, Rows는 Close/소진해야 하며, retry는 새 Tx에서 전체 unit을 다시 실행한다.

P08P08 · Background workerdurable DB state와 bounded execution queue를 결합해 crash와 duplicate를 견디는 delivery worker를 만든다.16 sections#p08

학습 목표

  • bounded queue·worker lifecycle·retry/jitter와 graceful drain을 구현한다.
  • poison job·deduplication·checkpoint·unknown outcome·restart를 reconciliation으로 복구한다.

필수 주제

bounded queue와 worker lifecycleretry와 jitter, poison jobidempotency와 deduplicationprocess restart와 checkpointunknown outcome과 reconciliationgraceful drain

직접 만들 산출물

  • internal/worker
  • internal/provider
  • integration
  • lab/failures

1. 실체와 오해

RECOMMENDED PRACTICE

in-memory channel은 scheduling queue일 수 있지만 process crash 뒤 durable queue가 아니다.

SPEC

process kill은 defer와 graceful cleanup 실행을 보장하지 않는다.

RECOMMENDED PRACTICE

end-to-end exactly-once delivery를 쉽게 주장하지 않는다. durable state, idempotency key와 reconciliation으로 at-least-once 시도를 안전하게 만든다.

2. 선수 지식

RECOMMENDED PRACTICE

context, channel ownership, DB transaction, idempotency와 provider failure semantics를 복습한다.

PROJECT POLICY

job state machine과 허용 transition을 코드·DB constraint·문서에서 일치시킨다.

3. 15분 개념

PROJECT POLICY

ready job을 lease와 함께 claim하고, bounded worker가 provider를 호출한 뒤 delivered/retry_at/dead를 기록한다.

reconciler는 expired lease와 unknown outcome을 재검사하고 checkpoint는 durable progress를 나타낸다.

RECOMMENDED PRACTICE

exponential backoff에 bounded jitter와 max attempts/age를 더해 synchronized retry를 흩뜨린다.

PROJECT POLICY

validation/permanent provider failure는 poison/dead 상태로 격리하고 자동 무한 retry하지 않는다.

4. runtime 내부

VERIFIED BEHAVIOR

worker process는 DB durable state를 source of truth로 두고 channel에는 claim된 immutable Job snapshot만 둔다.

PROJECT POLICY

claim에는 owner token과 lease_until을 두고 result update는 token/state 조건으로 fencing한다.

RECOMMENDED PRACTICE

provider 요청 후 response 전에 connection이 끊기면 side effect 성공 여부는 unknown이다. blind retry 전 provider idempotency/status API를 사용한다.

5. 최소 코드

PROJECT POLICY

Clock와 random source를 주입한 retry planner가 next attempt를 결정한다.

PROJECT POLICY

backoff 계산은 overflow를 막고 cap 뒤 full/equal jitter 중 선택한 policy를 문서화한다.

type RetryPlan struct {
    Base, Max time.Duration
    Attempts int
    Random func(time.Duration) time.Duration
}

func (p RetryPlan) Delay(attempt int) (time.Duration, bool) {
    if attempt >= p.Attempts { return 0, false }
    d := p.Base
    for i := 0; i < attempt && d < p.Max/2; i++ { d *= 2 }
    if d > p.Max { d = p.Max }
    return p.Random(d), true // full jitter in [0,d)
}

6. production 확장

RECOMMENDED PRACTICE

dispatcher poll batch→bounded channel→provider-partitioned workers→result writer와 별도 reconciler를 process lifecycle 아래 둔다.

PROJECT POLICY

provider와 tenant별 concurrency/rate budget을 global bound 안에서 적용한다.

PROJECT POLICY

HTTP idempotency key와 provider delivery key를 구분하되 notification ID로 안정적으로 연결한다.

7. 코드 해부

PROJECT POLICY

ready→leased→sending→delivered/retry_wait/unknown/dead transition마다 transaction, external call과 crash window를 표시한다.

RECOMMENDED PRACTICE

DB commit 전/후와 provider side effect 전/후의 네 crash window를 빠짐없이 분석한다.

PROJECT POLICY

result writer 실패 시 memory success를 최종 truth로 삼지 않고 reconciliation 대상 unknown으로 남긴다.

8. 호출·goroutine·memory trace

PROJECT POLICY

notification ID를 HTTP span, DB rows, worker attempt, provider idempotency key와 reconciliation span에 연결한다.

PROJECT POLICY

attempt number와 state는 bounded attribute이고 tenant ID는 metric label이 아니다.

RECOMMENDED PRACTICE

queue wait와 service time을 별도 span/event로 나눠 saturation과 provider latency를 구분한다.

9. 실패 주입

PROJECT POLICY

worker retry storm, 중복 notification, provider 성공 직후 process kill과 재처리를 강제 실습한다.

PROJECT POLICY

retry storm test는 동일 실패 시각의 N jobs가 jitter와 global/provider rate bound로 분산되는지 histogram으로 검증한다.

PROJECT POLICY

kill test는 subprocess를 provider acknowledgement 직후 종료하고 restart/reconciler가 같은 delivery key로 복구해 provider side effect가 하나임을 assert한다.

10. 테스트

PROJECT POLICY

fake clock deterministic unit, real DB/provider integration, subprocess kill/restart와 race test를 층별로 둔다.

PROJECT POLICY

중복 test는 attempt 수가 아니라 external side-effect count와 final durable state를 assert한다.

RECOMMENDED PRACTICE

lease expiry와 old owner result의 fencing을 two-worker deterministic interleaving으로 검증한다.

11. 성능

RECOMMENDED PRACTICE

claim batch, poll interval, worker/concurrency, provider limit과 result batch를 queue age·DB lock·throughput·tail latency로 조정한다.

PROJECT POLICY

load test는 provider slow/failure ratio를 바꾸며 bounded memory와 stable retry rate를 확인한다.

RECOMMENDED PRACTICE

poll interval 감소를 latency 해결책으로 단정하지 않고 DB load와 notification SLO를 함께 측정한다.

12. 보안

PROJECT POLICY

job payload는 최소화·암호화/retention 정책을 적용하고 tenant credential은 delivery 시 secret store에서 resolve한다.

RECOMMENDED PRACTICE

poison payload가 worker panic/retry loop나 log injection을 만들지 않도록 validate·bound·escape한다.

PROJECT POLICY

dead-letter 조회와 replay는 tenant-aware authorization와 audit log를 요구한다.

13. 운영

PROJECT POLICY

queue depth/oldest age, ready/leased/retry/unknown/dead, attempts, lease expiry, duplicate suppression, provider rate/error와 reconciliation lag를 운영한다.

RECOMMENDED PRACTICE

retry storm runbook은 provider circuit/rate control, enqueue protection, selective pause와 safe replay 순서를 포함한다.

14. 산출물

PROJECT POLICY

state diagram, dispatcher/pool/reconciler, fake-clock tests, retry histogram, duplicate/kill evidence와 drain log를 제출한다.

PROJECT POLICY

artifact 경로는 internal/worker, internal/provider, integration, lab/failures다.

15. 완료 조건

PROJECT POLICY

bounded queue/lifecycle/retry/jitter/poison/idempotency/dedup/restart/checkpoint/unknown/reconciliation/drain을 설명하고 세 강제 failure에서 side effect와 memory bound를 검증하면 완료다.

PROJECT POLICY

exactly-once라는 표현은 end-to-end proof 없이는 사용하지 않는다.

16. 자가시험

RECOMMENDED PRACTICE

질문: DB에 delivered 기록 전 provider 성공 후 crash하면 상태는 무엇인가? jitter만 있으면 storm이 해결되는가? graceful drain이 kill -9에도 작동하는가?

RECOMMENDED PRACTICE

unknown outcome, bound/rate/fairness, ungraceful termination 경계로 답한다.

자가시험 힌트

unknown이며 reconciliation이 필요하다. jitter만으로는 부족하고, kill -9에는 drain이 실행되지 않는다.

P09P09 · 테스트deterministic unit부터 실제 dependency·race·fuzz·load·subprocess failure까지 증거 층을 만든다.16 sections#p09

학습 목표

  • test double을 contract에 맞게 선택하고 concurrency/time을 deterministic하게 제어한다.
  • race, fuzz, benchmark, load와 failure suite의 주장 범위를 구분한다.

필수 주제

table-driven test와 httptestintegration과 Testcontainers 또는 실제 dependencyrace detector와 fuzzbenchmarkfake clock와 deterministic concurrency testfailure injectionload test

직접 만들 산출물

  • integration
  • internal/httpapi/fuzz_test.go
  • load
  • lab/failures

1. 실체와 오해

VERIFIED BEHAVIOR

passing test는 실행된 input·schedule·dependency 범위의 evidence다. production workflow 전체의 증명은 아니다.

VERIFIED BEHAVIOR

race detector는 실행 중 관찰한 data race를 보고한다. 미실행 path의 race absence를 보장하지 않는다.

VERIFIED BEHAVIOR

fuzzing은 seed corpus와 생성 input으로 invariant 위반을 탐색하며 exhaustive proof가 아니다.

2. 선수 지식

RECOMMENDED PRACTICE

pure function, interface seam, context, state machine, percentile와 reproducibility를 복습한다.

PROJECT POLICY

각 test는 검증 layer, dependency, clock/scheduler control과 expected claim을 이름/문서에 남긴다.

3. 15분 개념

RECOMMENDED PRACTICE

table-driven unit은 input/expected matrix, httptest는 handler/client HTTP contract, integration은 real DB/provider interaction을 검증한다.

race는 synchronization, fuzz는 broad input, benchmark는 controlled cost, load는 system saturation, failure test는 recovery invariant를 겨냥한다.

PROJECT POLICY

mock으로 DB isolation, driver cancellation, TCP reuse나 process restart를 검증했다고 주장하지 않는다.

RECOMMENDED PRACTICE

fake는 semantic behavior를 구현하고 mock expectation count보다 state/output invariant를 우선한다.

4. runtime 내부

VERIFIED BEHAVIOR

go test는 package test binary를 만들고 cache할 수 있다. -count=1, -race, -fuzz, -bench는 목적에 맞게 cache/schedule/instrumentation을 바꾼다.

VERIFIED BEHAVIOR

race instrumentation은 timing과 resource use를 바꾸므로 race 결과와 uninstrumented 성능 결과를 섞지 않는다.

SPEC

benchmark loop count는 harness가 정하고 code는 b.N 또는 지원 version의 newer benchmark API contract를 따라야 한다.

5. 최소 코드

PROJECT POLICY

decoder fuzz는 panic-free, bounded result와 domain invariant를 검증하고 known valid/invalid seed를 포함한다.

PROJECT POLICY

fuzz target은 network/DB를 직접 호출하지 않고 fast deterministic boundary를 선택한다.

func FuzzDecodeNotification(f *testing.F) {
    f.Add([]byte("{}"))
    f.Add([]byte("{"))
    f.Fuzz(func(t *testing.T, raw []byte) {
        if len(raw) > 1<<16 { t.Skip() }
        n, err := decodeNotification(raw)
        if err == nil {
            if n.Channel == "" || len(n.Body) > maxBody { t.Fatalf("invalid accepted value") }
        }
    })
}

6. production 확장

PROJECT POLICY

PR fast suite(unit/httptest), race suite, integration dependency suite, scheduled fuzz/load/failure와 release smoke를 분리한다.

PROJECT POLICY

DB/provider image와 Go/tool versions를 고정하고 clean-install runner에서 README 명령을 그대로 실행한다.

RECOMMENDED PRACTICE

flaky test를 무한 retry해 숨기지 말고 seed, schedule, logs와 artifacts를 보존해 quarantine owner/expiry를 둔다.

7. 코드 해부

RECOMMENDED PRACTICE

notification acceptance→DB row→worker attempt→provider side effect→reconciliation에 unit/integration/failure assertion이 어디 붙는지 coverage map을 만든다.

PROJECT POLICY

critical transition마다 happy, retryable, permanent, cancellation, duplicate와 crash case가 적어도 하나 있다.

RECOMMENDED PRACTICE

code coverage percentage는 gap 탐색 도구이지 quality 목표 단독 지표가 아니다.

8. 호출·goroutine·memory trace

PROJECT POLICY

deterministic concurrency test는 barrier A/B, ownership transfer, cancellation acknowledgement와 expected happens-before graph를 test log에 남긴다.

PROJECT POLICY

Go 1.25 module floor에서 testing/synctest를 사용할 수 있지만, 이 프로젝트의 portable seam은 injected clock/channel barrier도 유지하고 version scope를 표시한다.

RECOMMENDED PRACTICE

failed race/fuzz에는 exact command, GOOS/GOARCH, Go version, seed/corpus와 relevant log를 보존한다.

9. 실패 주입

PROJECT POLICY

강제 장애 12종을 test catalog로 유지하고 subprocess, proxy/fake provider, real DB restart와 signal로 안전하게 주입한다.

PROJECT POLICY

goroutine leak, channel close panic, nil interface, slice alias, concurrent map write, body/DB leak, context 미전파, retry storm, duplicate, kill/reprocess, shutdown timeout에 각각 expected symptom과 recovery invariant가 있다.

RECOMMENDED PRACTICE

failure injection은 production/public endpoint로 노출하지 않고 test build/config에서만 활성화한다.

10. 테스트

PROJECT POLICY

필수 command matrix는 unit, integration, race, representative fuzz, benchmark, load smoke와 failure test를 분리한다.

PROJECT POLICY

macOS/Linux shell과 PowerShell에서 동일한 go command를 제공하고 executable/path 차이는 scripts로 감싼다.

PROJECT POLICY

integration은 Docker 경로와 local dependency 경로를 모두 문서화하되 각 실행 결과를 별도 기록한다.

11. 성능

RECOMMENDED PRACTICE

benchmark는 setup을 timer 밖에 두고 allocation을 보고하며 여러 run을 비교한다. load test는 arrival rate, duration, dataset과 machine을 고정한다.

PROJECT POLICY

go test -bench=. -benchmem 결과와 load p50/p95/p99, error, saturation을 artifact로 저장한다.

RECOMMENDED PRACTICE

microbenchmark 개선을 end-to-end throughput 개선으로 표현하지 않는다.

12. 보안

PROJECT POLICY

test corpus, fixture, snapshot, failure log와 container env에 production secret/PII를 넣지 않는다.

RECOMMENDED PRACTICE

fuzz-generated crash input은 공개 artifact 전에 secret-like data 여부를 확인한다.

PROJECT POLICY

test dependency container는 최소 port만 localhost에 bind하고 고정된 non-production credential을 쓴다.

13. 운영

RECOMMENDED PRACTICE

suite duration/flakiness, race findings, fuzz corpus/crashes, benchmark trend와 failure recovery time을 운영 지표로 본다.

PROJECT POLICY

release gate failure는 owner와 evidence link가 있고 bypass에는 expiry와 risk acceptance가 필요하다.

14. 산출물

PROJECT POLICY

test matrix, real-dependency logs, race report, fuzz corpus, benchmark/load 결과와 12-failure catalog를 제출한다.

PROJECT POLICY

artifact 경로는 integration, internal/httpapi/fuzz_test.go, load, lab/failures다.

15. 완료 조건

PROJECT POLICY

table/httptest/integration/real dependency/race/fuzz/benchmark/fake clock/deterministic/failure/load를 실행하고 각 결과의 claim limit를 설명하면 완료다.

PROJECT POLICY

actual learner completion speed와 error reduction은 사용자 테스트 전까지 unverified다.

16. 자가시험

VERIFIED BEHAVIOR

질문: race test 한 번 통과하면 race-free인가? httptest.ResponseRecorder가 disconnect를 검증하는가? benchmark ns/op 개선이 SLO 개선인가?

VERIFIED BEHAVIOR

모두 evidence 범위를 넘는 주장인지 판별한다.

자가시험 힌트

모두 아니다. 실행 path, in-memory handler boundary, microbenchmark라는 한계가 있다.

P10P10 · 성능과 운영profile·execution trace·OpenTelemetry·structured log를 saturation과 배포 의사결정에 연결한다.16 sections#p10

학습 목표

  • CPU/heap/allocation/goroutine/mutex/block profile과 execution trace를 올바른 질문에 사용한다.
  • telemetry, container limit, canary·rollback과 runbook으로 capstone을 운영한다.

필수 주제

pprof, CPU profile, heap/allocation profilegoroutine dump, mutex/block profileexecution traceOpenTelemetry와 structured loggingqueue/pool saturation과 container limitscanary, rollback, runbook

직접 만들 산출물

  • internal/observability
  • profiles
  • runbooks
  • load

1. 실체와 오해

VERIFIED BEHAVIOR

profile, runtime execution trace와 distributed trace는 서로 다른 질문에 답한다. 하나로 나머지를 대체하지 않는다.

VERIFIED BEHAVIOR

CPU profile은 active CPU sample, heap profile은 allocation/live-object sample, goroutine profile은 stack snapshot, execution trace는 scheduler/GC/syscall event timeline을 제공한다.

RECOMMENDED PRACTICE

관측 도구 자체 overhead와 sampling bias를 workload에서 측정한다.

2. 선수 지식

RECOMMENDED PRACTICE

latency percentile, throughput, utilization/saturation/error, label cardinality, SLI/SLO와 container resource를 복습한다.

PROJECT POLICY

먼저 user-visible SLI와 hypothesis를 적고 그 질문에 맞는 profile/trace/metric을 선택한다.

3. 15분 개념

RECOMMENDED PRACTICE

profile은 비용이 쌓인 code path, runtime trace는 goroutine scheduling과 blocking, distributed trace는 service 간 request latency를 보여준다.

metric은 시간 추세와 alert, structured log는 discrete event context, runbook은 signal에서 안전한 action으로 가는 절차를 제공한다.

PROJECT POLICY

notification SLI는 durable acceptance latency, delivery latency/success, duplicate side effect와 queue oldest age를 분리한다.

RECOMMENDED PRACTICE

RED request 신호와 USE resource 신호를 queue/DB/provider에 맞게 조합한다.

4. runtime 내부

VERIFIED BEHAVIOR

block/mutex profile은 기본적으로 필요한 sampling을 enable해야 하며 profiler 동시 수집은 서로 간섭할 수 있다.

VERIFIED BEHAVIOR

execution trace는 scheduling, syscall, GC, heap 등 event를 담지만 CPU hotspot 분석에는 CPU profile이 더 직접적이다.

VERIFIED BEHAVIOR

Go 1.25 runtime의 default GOMAXPROCS는 container CPU bandwidth limit을 고려하고 주기적으로 갱신할 수 있다. explicit setting과 GODEBUG가 동작을 바꿀 수 있으므로 effective value를 startup telemetry에 기록한다.

5. 최소 코드

PROJECT POLICY

public API와 분리된 diagnostic listener에서 profile을 수집하고 exact command와 workload를 저장한다.

PROJECT POLICY

profile filename에는 commit, Go version, workload, duration과 before/after를 포함한다.

go tool pprof -top http://127.0.0.1:6060/debug/pprof/profile?seconds=30
go tool pprof -top http://127.0.0.1:6060/debug/pprof/heap
go tool pprof -top http://127.0.0.1:6060/debug/pprof/allocs
curl -o profiles/goroutine.txt 'http://127.0.0.1:6060/debug/pprof/goroutine?debug=2'
curl -o profiles/trace.out 'http://127.0.0.1:6060/debug/pprof/trace?seconds=5'
go tool trace profiles/trace.out

6. production 확장

PROJECT POLICY

HTTP→DB→worker→provider→reconciliation에 OpenTelemetry span을 연결하고 queue/pool/provider metric과 JSON log를 correlation ID로 결합한다.

RECOMMENDED PRACTICE

OpenTelemetry trace와 metric API/SDK stability를 dependency version에서 확인하고 log signal의 maturity는 별도로 검토한다.

PROJECT POLICY

sampling은 error/slow path 진단 가능성과 telemetry budget을 함께 만족하도록 config로 둔다.

7. 코드 해부

PROJECT POLICY

각 metric에서 type, unit, label set, cardinality bound, owner, alert/SLO 연결을 검토한다.

PROJECT POLICY

tenant ID, notification ID, request ID, URL raw path와 error message는 metric label이 아니다.

RECOMMENDED PRACTICE

log는 timestamp/level/message/service/operation/request or trace ID/stable error code를 구조화하고 payload/secret을 redact한다.

8. 호출·goroutine·memory trace

VERIFIED BEHAVIOR

load 증가에서 queue age→DB pool wait→runnable goroutine→provider latency→GC/allocation이 변하는 timeline을 metric, runtime trace, profile과 distributed span으로 교차 검증한다.

RECOMMENDED PRACTICE

상관관계는 원인 증명이 아니다. controlled injection과 before/after counterfactual로 hypothesis를 시험한다.

PROJECT POLICY

trace에는 workload arrival rate, container limits와 active config를 첨부한다.

9. 실패 주입

PROJECT POLICY

CPU hotspot, allocation retention, mutex/block contention, queue/DB saturation, provider slowdown, telemetry exporter outage와 graceful shutdown timeout을 주입한다.

PROJECT POLICY

telemetry backend 장애가 request/worker를 무기한 block하지 않으며 bounded buffer/drop policy와 self-metric이 동작해야 한다.

PROJECT POLICY

shutdown timeout에서는 readiness off, intake stop, in-flight/worker drain, diagnostic dump, hard stop 순서를 evidence로 남긴다.

10. 테스트

PROJECT POLICY

metric registration/unit, span propagation/export, JSON log schema/redaction, profile endpoint isolation과 alert/runbook link를 test한다.

RECOMMENDED PRACTICE

golden telemetry는 nondeterministic timestamp/IDs를 normalize하고 semantic field를 assert한다.

PROJECT POLICY

load/failure run은 telemetry가 없거나 과도한 cardinality일 때 fail하는 source/runtime validation을 포함한다.

11. 성능

PROJECT POLICY

baseline→hypothesis→single profiler→change→same workload comparison 순서로 CPU/heap/allocation/mutex/block을 수집한다.

RECOMMENDED PRACTICE

production profile은 제한된 replica/duration에서 overhead를 먼저 측정하고 한 번에 하나의 expensive profile을 수집한다.

PROJECT POLICY

optimization acceptance는 SLO 또는 resource cost 개선과 regression test를 요구한다.

12. 보안

PROJECT POLICY

pprof, expvar/metrics, trace와 admin health detail은 private authenticated diagnostic surface다.

RECOMMENDED PRACTICE

heap/goroutine/profile은 payload, URL, stack argument와 credential을 간접 노출할 수 있어 access·retention·redaction 정책을 둔다.

PROJECT POLICY

structured log injection을 막고 exporter endpoint/TLS credential을 secret 관리한다.

13. 운영

PROJECT POLICY

canary는 acceptance/delivery SLI, queue age, duplicate, resource/profile regression과 telemetry health를 baseline과 비교하고 자동/수동 rollback 조건을 가진다.

RECOMMENDED PRACTICE

rollback이 schema/state 호환성을 되돌릴 수 없으면 forward-fix와 traffic control plan이 필요하다.

PROJECT POLICY

runbook은 symptom→confirming queries/profile→safe mitigation→escalation→recovery verification 순서다.

14. 산출물

PROJECT POLICY

OTel wiring, metric catalog, log schema, CPU/heap/alloc/goroutine/mutex/block/trace evidence, dashboard/alerts, canary/rollback plan과 runbooks를 제출한다.

PROJECT POLICY

artifact 경로는 internal/observability, profiles, load, runbooks다.

15. 완료 조건

PROJECT POLICY

각 profile/trace/telemetry의 질문과 한계를 설명하고 saturation/container/canary/rollback/runbook을 failure evidence로 검증하면 완료다.

PROJECT POLICY

dashboard가 존재한다는 사실은 product/workflow 검증이 아니다. 실제 incident drill 성공은 별도로 unverified다.

16. 자가시험

VERIFIED BEHAVIOR

질문: CPU profile로 goroutine deadlock 원인을 가장 잘 찾는가? heap inuse와 allocs는 같은가? trace ID를 metric label로 써도 되는가?

RECOMMENDED PRACTICE

질문-도구 적합성, live/total allocation, cardinality bound로 답한다.

자가시험 힌트

모두 아니다. deadlock은 dump/block/trace, heap과 allocs는 다른 view, trace ID는 high cardinality다.

BOUNDARY TABLE

약속, 구현, 정책을 섞지 않기

Go 언어가 보장하는 것과 runtime 구현, 이 프로젝트의 선택을 분리해야 업그레이드와 장애 분석이 안전해집니다.

주제SPEC구현 관찰프로젝트 정책검증 방법
goroutine vs schedulergo 문은 새 goroutine에서 함수를 시작한다.gc runtime은 Go 1.25에서 G/M/P, run queues, stealing과 netpoll을 사용한다.correctness는 exact G/M/P 순서에 의존하지 않는다.go tool trace와 versioned runtime source
stack·escape·heap언어 사양은 local value의 물리 배치를 약속하지 않는다.compiler escape analysis와 movable goroutine stacks가 배치를 결정한다.escape report는 profile과 대조한다.-gcflags=-m=2, alloc/heap profile
slice vs backing arrayslice는 underlying array 구간이며 append는 새 slice를 반환한다.capacity가 충분하면 current implementation은 storage를 재사용할 수 있고 growth policy는 변할 수 있다.ownership boundary에서 clone한다.cap 양쪽 table test와 race test
nil interfacedynamic type/value가 모두 없을 때 interface가 nil이다.concrete representation layout은 사양이 아니다.error-returning path의 typed nil을 test한다.nil comparison과 errors.As table
memory model vs race detectorhappens-before와 DRF-SC가 correctness contract다.race detector는 실행 path를 instrument한다.barrier tests와 -race를 모두 쓴다.go test -race plus adversarial interleavings
cancellation signal vs stopparent cancellation은 child Done을 닫는다.driver/callee가 signal을 얼마나 빨리 관찰하는지는 구현에 달렸다.모든 DB/HTTP call에 ctx와 자체 bound를 전달한다.client-disconnect real-listener test
HTTP connection vs request goroutineServer.Serve는 accepted connection당 service goroutine을 문서화한다.HTTP/1 handler와 HTTP/2 stream의 concurrency 구조가 다르고 release에 따라 변할 수 있다.goroutine-per-request를 universal contract로 표현하지 않는다.protocol별 trace와 Go 1.25 source
HTTP resource creation vs deliveryHTTP status는 application protocol이 정한다.worker/provider는 response 뒤 별도 lifetime에서 처리된다.새 resource는 201+Location, idempotent replay는 200이며 둘 다 provider delivery 완료를 뜻하지 않는다.API schema plus restart integration test
database/sql vs databasedatabase/sql은 pool/Tx/Rows API contract를 제공한다.SQLite driver와 database가 locking, cancellation, isolation/error details를 정한다.pinned real dependency에서 integration한다.modernc/sqlite 1.53.0 integration and restart tests
attempt vs exactly-onceGo/HTTP/SQL은 end-to-end exactly-once를 보장하지 않는다.provider idempotency/status capability가 unknown-outcome recovery 범위를 정한다.at-least-once attempts + stable delivery key + reconciliation을 사용한다.kill-after-provider-success side-effect count
profile vs trace표준 library는 profile/trace API를 공개한다.sampling, overhead와 event detail은 version/workload에 의존한다.질문별 한 도구를 baseline과 같은 workload에서 비교한다.CPU/heap/block/trace before-after artifacts
cross-build vs OS executionGOOS/GOARCH는 target build selection에 관여한다.OS scheduler, signals, sockets와 filesystem behavior는 target에서만 실행된다.darwin/windows compile과 actual runner 검증을 분리한다.cross-build matrix plus native runner logs
test pass vs learning effecttoolchain은 test execution result만 보고한다.학습 효과는 사람의 prior knowledge와 task design에 좌우된다.Product/workflow 검증은 사용자 test 전까지 unverified다.task completion time, errors, explanation rubric

GLOSSARY

대규모 Go 코드를 읽는 공용어

goroutineP00SPEC
다른 함수 호출과 독립적으로 동시에 실행되는 Go 실행 단위. OS thread와 일대일 계약이 아니다.
G/M/PP00VERIFIED BEHAVIOR
현재 gc runtime scheduler의 goroutine, OS thread, 실행 resource 모델. 언어 사양이 아니다.
work stealingP00VERIFIED BEHAVIOR
idle scheduler resource가 다른 run queue에서 runnable work를 찾는 현재 runtime 기법.
escape analysisP00VERIFIED BEHAVIOR
compiler가 값의 lifetime과 alias를 보수적으로 분석해 stack에 둘 수 있는지 결정하는 과정.
GCP00VERIFIED BEHAVIOR
도달 불가능한 heap object의 storage를 회수하는 runtime 기능. pause/throughput 세부는 구현·버전에 의존한다.
backing arrayP01SPEC
slice가 참조하는 underlying array. 여러 slice가 같은 element storage를 공유할 수 있다.
method setP01SPEC
type 또는 pointer type이 가진 method 집합으로 interface 구현과 method expression 가능성을 정한다.
typed nilP01SPEC
dynamic type은 있지만 dynamic value가 nil인 interface content. interface 자체의 nil과 다르다.
runeP01SPEC
int32의 alias이며 Unicode code point를 나타내는 convention. grapheme cluster와 같지 않다.
최소 버전 선택(MVS)P02SPEC
module requirement graph에서 각 module path의 selected version을 정하는 Go 규칙.
internal packageP02SPEC
허용된 ancestor tree 밖에서 import할 수 없도록 go command가 제한하는 package.
재현 가능한 buildP02RECOMMENDED PRACTICE
동일한 declared source/tool/input에서 식별 가능한 동일 결과를 다시 만드는 성질. warm cache hit와 다르다.
error chainP03SPEC
wrap된 error와 Unwrap 관계를 errors.Is/As가 탐색하는 구조.
retryable errorP03PROJECT POLICY
같은 semantic operation을 policy와 idempotency 아래 다시 시도할 수 있다고 분류한 실패.
happens-beforeP04SPEC
한 memory operation의 효과가 다른 operation에 보이도록 정하는 memory model의 partial order.
data raceP04SPEC
동시에 같은 memory location에 접근하고 하나 이상이 write이며 적절한 synchronization이 없는 실행.
backpressureP04RECOMMENDED PRACTICE
consumer capacity 부족을 producer의 block, reject 또는 rate 조절로 전달하는 제어.
ContextP05SPEC
deadline, cancellation signal과 request-scoped value를 API boundary에 전달하는 standard interface.
deadlineP05SPEC
작업이 끝나야 하는 절대 시각. timeout은 보통 현재 시각에서 deadline을 만드는 duration이다.
connection service goroutineP06VERIFIED BEHAVIOR
Server.Serve가 accepted connection마다 시작한다고 문서화한 goroutine.
HTTP TransportP06VERIFIED BEHAVIOR
outbound HTTP request의 dial, TLS, proxy와 connection pooling/reuse를 구현하는 RoundTripper.
idempotency keyP06PROJECT POLICY
같은 semantic request의 retry를 하나의 durable result에 연결하는 client-supplied identifier.
DB connection poolP07VERIFIED BEHAVIOR
database/sql DB가 idle/in-use physical connection과 대기 caller를 관리하는 자원 경계.
transaction isolationP07VERIFIED BEHAVIOR
동시 transaction의 change가 서로 어떻게 관찰되는지 제한하는 database contract.
leaseP08PROJECT POLICY
worker가 job을 제한된 기간 소유한다고 durable state에 기록하는 claim.
fencing tokenP08RECOMMENDED PRACTICE
expired owner의 늦은 write를 거부하기 위해 claim generation/owner를 조건에 넣는 값.
poison jobP08RECOMMENDED PRACTICE
반복해도 성공하지 않는 invalid/permanent job. bounded attempts 뒤 격리한다.
unknown outcomeP08RECOMMENDED PRACTICE
timeout/connection loss 때문에 external side effect 성공 여부를 알 수 없는 상태.
reconciliationP08RECOMMENDED PRACTICE
durable state와 external truth를 다시 비교해 expired/unknown state를 수렴시키는 과정.
fuzzingP09VERIFIED BEHAVIOR
seed와 생성 input으로 test invariant를 반복 탐색하고 최소 failing input을 보존하는 test 방식.
profileP10VERIFIED BEHAVIOR
일정 기간의 CPU, allocation 또는 contention cost sample을 code path에 집계한 진단 자료.
runtime execution traceP10VERIFIED BEHAVIOR
한 process의 goroutine scheduling, syscall, GC 등 runtime event timeline.
distributed traceP10RECOMMENDED PRACTICE
process/service 경계를 넘는 request operation을 span causality로 연결한 telemetry.
metric cardinalityP10RECOMMENDED PRACTICE
metric label 조합이 만들 수 있는 distinct time series 수.
saturationP10RECOMMENDED PRACTICE
queue, pool, CPU 같은 resource가 capacity에 묶여 work가 대기·거절되는 상태.
SLI/SLOP10RECOMMENDED PRACTICE
사용자 관찰 가능 service indicator와 그 indicator의 목표 범위.
graceful shutdownP10PROJECT POLICY
새 work 유입을 멈추고 deadline 안에서 in-flight work를 drain한 뒤 resource를 닫는 종료 정책.

PRIMARY SOURCES

설명보다 원문에 가까이

  1. Go 언어 사양 (새 탭에서 열림)

    초기화, type, method set, interface, map/range, defer/panic의 SPEC 근거.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P01, P03, P04
  2. Go slices: usage and internals (새 탭에서 열림)

    slice descriptor, length/capacity와 backing array를 설명하는 공식 Go 자료. 구체 growth policy의 사양은 아니다.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P01
  3. Go Memory Model (새 탭에서 열림)

    happens-before, synchronization, race와 DRF-SC 근거.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P04
  4. Runtime 내부 안내 (새 탭에서 열림)

    G/M/P 용어와 runtime coding model. 언어 계약이 아니다.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00
  5. runtime scheduler source (새 탭에서 열림)

    Go 1.25와 함께 읽어야 하는 scheduler/work-stealing/syscall 구현 근거.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P04
  6. runtime network poller source (새 탭에서 열림)

    network poller 구현 근거. OS별 파일과 함께 해석한다.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P06
  7. Go GC 안내 (새 탭에서 열림)

    GC cost model, GOGC와 memory-limit 운영 설명.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P10
  8. cgo command 문서 (새 탭에서 열림)

    cgo pointer/pinning, build와 platform boundary.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P02
  9. Go Modules Reference (새 탭에서 열림)

    go.mod, MVS, replace, vendoring과 module graph.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P02
  10. Multi-module workspace tutorial (새 탭에서 열림)

    go.work와 workspace mode의 공식 안내.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P02
  11. errors package 문서 (새 탭에서 열림)

    Is/As/Join/Unwrap의 공개 API contract.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P03
  12. context package 문서 (새 탭에서 열림)

    tree, cancellation, values, CancelFunc와 WithoutCancel contract.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P05
  13. net/http package 문서 (새 탭에서 열림)

    Server, Client, Transport, body와 shutdown public contract.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P05, P06
  14. net/http server source (새 탭에서 열림)

    accepted connection service goroutine와 HTTP/1 handler flow의 implementation 근거.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P06
  15. net/http HTTP/2 bundled source (새 탭에서 열림)

    HTTP/2 stream/handler scheduling의 version-sensitive 근거.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P06
  16. database/sql package 문서 (새 탭에서 열림)

    DB pool, Tx, Rows, context와 pool-setting contract.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P05, P07
  17. modernc SQLite driver 문서 (새 탭에서 열림)

    고정된 1.53.0 driver의 API와 release information. database/sql 사양과 구분한다.

    modernc.org · 확인 2026-07-15 · 연결 모듈 P07, P09
  18. SQLite Write-Ahead Logging (새 탭에서 열림)

    WAL의 concurrency, checkpoint, persistence와 운영 제한에 대한 upstream 설명.

    SQLite Project · 확인 2026-07-15 · 연결 모듈 P07, P08, P09
  19. SQLite Transaction 문서 (새 탭에서 열림)

    DEFERRED/IMMEDIATE/EXCLUSIVE transaction과 commit/rollback 동작의 database contract.

    SQLite Project · 확인 2026-07-15 · 연결 모듈 P07, P08
  20. SQLite Result/Error Codes (새 탭에서 열림)

    BUSY, LOCKED, CONSTRAINT 등 retry/error 분류를 driver string이 아닌 result code에서 시작하기 위한 근거.

    SQLite Project · 확인 2026-07-15 · 연결 모듈 P03, P07, P08
  21. testing package 문서 (새 탭에서 열림)

    test, benchmark, fuzz와 Go 1.25 testing/synctest 관련 public contract.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P04, P09
  22. testing/synctest package 문서 (새 탭에서 열림)

    Go 1.25의 격리된 synthetic time/concurrency test package contract.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P04, P05, P09
  23. Data Race Detector (새 탭에서 열림)

    race 실행 방법, report와 한계.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P04, P09
  24. Go fuzzing tutorial (새 탭에서 열림)

    seed corpus, fuzz target와 command.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P09
  25. Go diagnostics (새 탭에서 열림)

    profile, trace, debug와 runtime statistic 선택 안내.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P10
  26. runtime/pprof package 문서 (새 탭에서 열림)

    CPU와 predefined profile API.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P10
  27. runtime/trace package 문서 (새 탭에서 열림)

    execution trace와 user task/region API.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P10
  28. runtime GOMAXPROCS 문서 (새 탭에서 열림)

    Go 1.25 container-aware default와 update/config 경계.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P10
  29. Go 1.25 release notes (새 탭에서 열림)

    module floor에 도입된 runtime/testing 변화의 version scope.

    The Go Authors · 확인 2026-07-15 · 연결 모듈 P00, P04, P09, P10
  30. OpenTelemetry Go 문서 (새 탭에서 열림)

    고정된 OTel Go 1.44.0을 구성할 때 signal status와 SDK 사용을 확인하는 upstream 문서.

    OpenTelemetry Authors · 확인 2026-07-15 · 연결 모듈 P10
  31. Docker multi-stage build (새 탭에서 열림)

    builder/runtime stage를 분리해 clean, minimal artifact를 만드는 공식 지침.

    Docker, Inc. · 확인 2026-07-15 · 연결 모듈 P02, P09, P10
  32. Docker resource constraints (새 탭에서 열림)

    CPU와 memory constraint 설정 및 risk의 공식 지침.

    Docker, Inc. · 확인 2026-07-15 · 연결 모듈 P00, P09, P10
  33. WCAG 2.2 (새 탭에서 열림)

    single-page 학습 UI의 keyboard, focus, contrast, reflow와 target-size 검수 근거.

    W3C · 확인 2026-07-15 · 연결 모듈 P09, P10

VERIFICATION LEDGER

통과한 것과 아직 모르는 것을 분리

01 · executable

Function verification

build, unit/integration, race, fuzz smoke, benchmark, load, failure 명령을 저장소에서 실행합니다.

02 · measured

Quality verification

콘텐츠 coverage, source URL, 접근성 구조, responsive layout을 별도 검사합니다.

03 · unverified

Product/workflow verification

실제 학습 효과와 대규모 코드 판독 속도 향상은 학습자 사용자 테스트 전까지 unverified입니다.

콘텐츠 구조 검사 통과