Repository navigation
Expand file tree
/
Copy pathannotation.go
More file actions
304 lines (283 loc) · 9.7 KB
/
Copy pathannotation.go
File metadata and controls
304 lines (283 loc) · 9.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
package axio
import (
"math"
"reflect"
"time"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
)
// Annotation represents a structured field attached to a log entry.
//
// Use [Field] to create annotations for simple key-value pairs.
// For complex types that produce multiple fields, implement [Annotable].
//
// The internal storage wraps a zapcore.Field directly to avoid a second
// type-switch on every log call. The field is unexported and unreachable
// through any method or signature on the public API; downstream consumers
// interact only via [Annotation.Name], [Annotation.Data] and [Annotation.Value]. This is a
// deliberate exception to the project rule that axio's public types use
// only axio-native types — the alternative would pay a per-call translation
// cost with no user-visible reward (godoc already hides unexported fields).
//
// Example:
//
// logger.Info(ctx, "user authenticated",
// axio.Field("user_id", "usr_123"),
// axio.Field("action", "login"),
// )
type Annotation struct {
field zapcore.Field
}
// Field creates an annotation with the given key and value.
//
// For primitive types (string, integers, floats, bool), the implementation
// is zero-allocation when inlined by the compiler. Complex types (structs,
// maps, slices) fall back to interface boxing.
//
// Example:
//
// axio.Field("user_id", "usr_123")
// axio.Field("count", 42)
// axio.Field("order", myOrder)
func Field[T any](key string, value T) Annotation {
switch concrete := any(value).(type) {
case string:
return Annotation{field: zap.String(key, concrete)}
case int:
return Annotation{field: zap.Int(key, concrete)}
case int64:
return Annotation{field: zap.Int64(key, concrete)}
case int32:
return Annotation{field: zap.Int32(key, concrete)}
case uint:
return Annotation{field: zap.Uint(key, concrete)}
case uint64:
return Annotation{field: zap.Uint64(key, concrete)}
case float64:
return Annotation{field: zap.Float64(key, concrete)}
case bool:
return Annotation{field: zap.Bool(key, concrete)}
default:
return uncommonField(key, value)
}
}
// Name returns the annotation key.
func (a Annotation) Name() string { return a.field.Key }
// Data returns the annotation value: int64 for a signed integer, uint64 for an
// unsigned one, float64 for a floating-point number, and any other value as it
// was given.
func (a Annotation) Data() any {
if value, ok := a.integerData(); ok {
return value
}
switch a.field.Type {
case zapcore.StringType:
return a.field.String
case zapcore.Float64Type:
return math.Float64frombits(uint64(a.field.Integer))
case zapcore.Float32Type:
return float64(math.Float32frombits(uint32(a.field.Integer)))
case zapcore.BoolType:
return a.field.Integer == 1
case zapcore.DurationType:
return time.Duration(a.field.Integer)
case zapcore.TimeType:
return a.moment()
case zapcore.ArrayMarshalerType:
return givenSlice(a.field.Interface)
default:
return a.field.Interface
}
}
// Value returns the annotation's value as a T, and whether it holds one. A
// number converts to any number type of its kind — signed, unsigned or
// floating point — that holds it exactly, so an annotation made from an int
// comes back as an int, an int64, or an int8 when it fits. Any other value must
// be a T.
//
// Example:
//
// if count, ok := annotation.Value[int](); ok {
// total += count
// }
func (a Annotation) Value[T any]() (T, bool) {
data := a.Data()
if value, ok := data.(T); ok {
return value, true
}
var value T
ok := convertNumber(data, reflect.ValueOf(&value).Elem())
return value, ok
}
// integerData returns the value of a field zap stores as an integer: int64 for
// a signed one, uint64 for an unsigned one or a uintptr.
func (a Annotation) integerData() (any, bool) {
switch a.field.Type {
case zapcore.Int64Type, zapcore.Int32Type, zapcore.Int16Type, zapcore.Int8Type:
return a.field.Integer, true
case zapcore.Uint64Type, zapcore.Uint32Type, zapcore.Uint16Type, zapcore.Uint8Type, zapcore.UintptrType:
return uint64(a.field.Integer), true
default:
return nil, false
}
}
// moment returns the time a TimeType field holds: nanoseconds since the epoch,
// in the location zap keeps beside them.
func (a Annotation) moment() time.Time {
moment := time.Unix(0, a.field.Integer)
if location, ok := a.field.Interface.(*time.Location); ok {
return moment.In(location)
}
return moment
}
// Annotations is a collection of annotations with helper methods.
type Annotations []Annotation
// Names returns the names of all annotations in the collection.
func (a Annotations) Names() []string {
names := make([]string, len(a))
for index := range a {
names[index] = a[index].field.Key
}
return names
}
// Data returns the values of all annotations in the collection.
func (a Annotations) Data() []any {
contents := make([]any, len(a))
for index := range a {
contents[index] = a[index].Data()
}
return contents
}
// Add adds a new annotation to the collection and returns the modified
// collection. Like [Field], it takes the value's type as a type parameter, so a
// value of a primitive type is kept without allocating.
func (a *Annotations) Add[T any](key string, value T) Annotations {
*a = append(*a, Field(key, value))
return *a
}
// Annotable allows complex types to produce annotations for log entries.
//
// Types that implement this interface can be passed to a level method or to
// [Logger.With] via [Field]. The logger detects the [Annotable]
// implementation and expands the annotations before the hooks run, so PII
// masking and custom hooks see each field on its own.
//
// Append appends the type's annotations to the provided slice and
// returns the extended slice.
//
// Example:
//
// func (h HTTP) Append(target []axio.Annotation) []axio.Annotation {
// return append(target,
// axio.Field("method", h.Method),
// axio.Field("url", h.URL),
// axio.Field("status_code", h.StatusCode),
// )
// }
type Annotable interface {
Append([]Annotation) []Annotation
}
// HTTP represents HTTP request metadata for structured logging.
//
// Use this annotation to add HTTP request context to logs,
// facilitating correlation and problem analysis.
//
// HTTP implements [Annotable] to produce individual fields for each
// request attribute.
//
// Example:
//
// http := axio.HTTP{
// Method: "POST",
// URL: "/api/v1/orders",
// StatusCode: 201,
// LatencyMS: 45,
// UserAgent: r.UserAgent(),
// ClientIP: r.RemoteAddr,
// }
// logger.Info(ctx, "request processed", axio.Field("http", http))
type HTTP struct {
// Method is the HTTP method (GET, POST, PUT, DELETE, etc).
Method string `json:"method"`
// URL is the request path.
URL string `json:"url"`
// StatusCode is the HTTP response code.
StatusCode int `json:"status_code"`
// LatencyMS is the request latency in milliseconds.
LatencyMS int64 `json:"latency"`
// UserAgent is the client's User-Agent header.
UserAgent string `json:"user_agent"`
// ClientIP is the client's IP address.
ClientIP string `json:"client_ip"`
}
// Append implements [Annotable] for HTTP request metadata.
func (h HTTP) Append(target []Annotation) []Annotation {
return append(target,
Field("method", h.Method),
Field("url", h.URL),
Field("status_code", h.StatusCode),
Field("latency", h.LatencyMS),
Field("user_agent", h.UserAgent),
Field("client_ip", h.ClientIP),
)
}
// uncommonField covers the primitive types [Field] does not switch on
// directly, falling back to interface boxing for everything else. The split
// keeps the common types on a single type switch.
func uncommonField[T any](key string, value T) Annotation {
switch concrete := any(value).(type) {
case int8:
return Annotation{field: zap.Int8(key, concrete)}
case int16:
return Annotation{field: zap.Int16(key, concrete)}
case uint8:
return Annotation{field: zap.Uint8(key, concrete)}
case uint16:
return Annotation{field: zap.Uint16(key, concrete)}
case uint32:
return Annotation{field: zap.Uint32(key, concrete)}
case float32:
return Annotation{field: zap.Float32(key, concrete)}
default:
return Annotation{field: zap.Any(key, value)}
}
}
// convertNumber sets target to number when target is a number type of the same
// kind that holds it exactly, and reports whether it did. The reflect.Value
// names the one boundary where the type of the target is known only to the
// caller of [Annotation.Value].
func convertNumber(number any, target reflect.Value) bool {
switch typed := number.(type) {
case int64:
return setNumber(target.CanInt, target.OverflowInt, target.SetInt, typed)
case uint64:
return setNumber(target.CanUint, target.OverflowUint, target.SetUint, typed)
case float64:
return setNumber(target.CanFloat, target.OverflowFloat, target.SetFloat, typed)
default:
return false
}
}
// setNumber sets number through set when the target is of its kind, as can
// reports, and holds it exactly, as overflows reports.
func setNumber[N int64 | uint64 | float64](can func() bool, overflows func(N) bool, set func(N), number N) bool {
if !can() || overflows(number) {
return false
}
set(number)
return true
}
// givenSlice returns a slice that zap keeps in one of its own array types — a
// []int as its ints, a []string as its stringArray — as the slice it was
// given, and any other value as it is. The reflect.Value names the boundary
// where zap's unexported types meet the caller's.
func givenSlice(value any) any {
array := reflect.ValueOf(value)
if array.Kind() != reflect.Slice || array.Type().PkgPath() != zapArrayPackage {
return value
}
return array.Convert(reflect.SliceOf(array.Type().Elem())).Interface()
}
// zapArrayPackage is the package of the array types zap.Any keeps a slice of a
// basic type in.
var zapArrayPackage = reflect.TypeOf(zap.Bools("", nil).Interface).PkgPath()