errorx

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	fmt.Println(errorx.CategoryOf(errorx.NotFound("X", "x")))
	fmt.Println(errorx.CategoryOf(errorx.Forbidden("X", "x")))
	fmt.Println(errorx.CategoryOf(errorx.Internal("X", "x")))
}

Output:
not_found
permission
internal

package main

import (
	"errors"
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// CodeOf returns the error code. nil → OK, unknown → INTERNAL_ERROR.
	fmt.Println(errorx.CodeOf(nil))
	fmt.Println(errorx.CodeOf(errors.New("unknown")))
	fmt.Println(errorx.CodeOf(errorx.NotFound("AIHUB_SKILL_NOT_FOUND", "x")))
}

Output:
OK
INTERNAL_ERROR
AIHUB_SKILL_NOT_FOUND

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

// errorCodeStringError mimics errors that expose ErrorCode() string method.
type errorCodeStringError struct {
	code string
	msg  string
}

func (e errorCodeStringError) Error() string     { return e.msg }
func (e errorCodeStringError) ErrorCode() string { return e.code }

func main() {
	// errorx recognizes ErrorCode() string method.
	foreignErr := errorCodeStringError{code: "CUSTOM_NOT_FOUND", msg: "x"}
	fmt.Println(errorx.CodeOf(foreignErr))
}

Output:
CUSTOM_NOT_FOUND

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// CodeOf(nil) returns OK — safe to call on any error.
	fmt.Println(errorx.CodeOf(nil))
}

Output:
OK

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// NormalizeCode converts empty code to INTERNAL_ERROR.
	fmt.Println(errorx.NormalizeCode(""))
	fmt.Println(errorx.NormalizeCode("AIHUB_CUSTOM"))
}

Output:
INTERNAL_ERROR
AIHUB_CUSTOM

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// As extracts *errorx.Error from an error chain.
	original := errorx.NotFound("AIHUB_SKILL_NOT_FOUND", "技能不存在")
	wrapped := fmt.Errorf("repo: %w", original)

	ke, ok := errorx.As(wrapped)
	fmt.Println(ok)
	fmt.Println(ke.Code())
}

Output:
true
AIHUB_SKILL_NOT_FOUND

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.BadRequest("REQUEST_VALIDATE_FAILED", "请求参数校验失败")
	fmt.Println(errorx.CodeOf(err))
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.GRPCCodeOf(err))
	fmt.Println(errorx.RetryableOf(err))
}

Output:
REQUEST_VALIDATE_FAILED
400
InvalidArgument
false

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.ClientClosed("CLIENT_CLOSED", "客户端断开连接")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.GRPCCodeOf(err))
	fmt.Println(errorx.SeverityOf(err))
}

Output:
499
Canceled
debug

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Conflict("AIHUB_SKILL_ALREADY_EXISTS", "技能已存在")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.CategoryOf(err))
}

Output:
409
conflict

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Forbidden("IAM_PERMISSION_DENIED", "权限被拒绝",
		errorx.WithMetadata("subject_id", "user_123"),
		errorx.WithPublicMetadata("resource", "skill"),
	)
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.PublicMetadataOf(err))
}

Output:
403
map[resource:skill]

package main

import (
	"errors"
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// From converts a foreign error to *errorx.Error.
	cause := errors.New("something failed")
	ke := errorx.From(cause)
	fmt.Println(ke.Code())
	fmt.Println(ke.HTTPStatus())
	fmt.Println(ke.Retryable())
}

Output:
INTERNAL_ERROR
500
false

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

// gofrStyleError mimics GoFr's error type with StatusCode() method.
type gofrStyleError struct {
	msg    string
	status int
}

func (e gofrStyleError) Error() string   { return e.msg }
func (e gofrStyleError) StatusCode() int { return e.status }

func main() {
	// errorx recognizes GoFr-style errors via StatusCode() method.
	gofrErr := gofrStyleError{msg: "not found", status: 404}
	ke := errorx.From(gofrErr)
	fmt.Println(ke.HTTPStatus())
	fmt.Println(ke.Code())
}

Output:
404
NOT_FOUND

package main

import (
	"errors"
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// From with options to override defaults.
	cause := errors.New("upstream timeout")
	ke := errorx.From(cause,
		errorx.WithHTTPStatus(504),
		errorx.WithRetryable(true),
		errorx.WithMetadata("upstream", "model-svc"),
	)
	fmt.Println(ke.HTTPStatus())
	fmt.Println(ke.Retryable())
	fmt.Println(ke.Metadata()["upstream"])
}

Output:
504
true
model-svc

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Internal("AIHUB_INTERNAL_ERROR", "服务器内部错误")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.CategoryOf(err))
	fmt.Println(errorx.SeverityOf(err))
}

Output:
500
internal
error

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// New creates a canonical Error with default mappings derived from code.
	err := errorx.New("AIHUB_CUSTOM_ERROR",
		errorx.WithMessage("自定义错误"),
		errorx.WithHTTPStatus(422),
	)
	fmt.Println(errorx.CodeOf(err))
	fmt.Println(errorx.MessageOf(err))
	fmt.Println(errorx.HTTPStatusOf(err))
}

Output:
AIHUB_CUSTOM_ERROR
自定义错误
422

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.NotFound("AIHUB_SKILL_NOT_FOUND", "技能不存在")
	fmt.Println(errorx.CodeOf(err))
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.RetryableOf(err))
}

Output:
AIHUB_SKILL_NOT_FOUND
404
false

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.RequestTimeout("HTTP_REQUEST_TIMEOUT", "请求超时")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.GRPCCodeOf(err))
}

Output:
408
DeadlineExceeded

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Timeout("MODEL_UPSTREAM_TIMEOUT", "模型上游超时")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.RetryableOf(err))
	fmt.Println(errorx.CategoryOf(err))
}

Output:
504
true
dependency

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.TooManyRequests("RATE_LIMIT_EXCEEDED", "请求过于频繁")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.RetryableOf(err))
}

Output:
429
true

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Unauthorized("AUTH_TOKEN_MISSING", "缺少授权令牌")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.CategoryOf(err))
}

Output:
401
auth

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Unavailable("MODEL_UPSTREAM_UNAVAILABLE", "模型上游不可用")
	fmt.Println(errorx.HTTPStatusOf(err))
	fmt.Println(errorx.RetryableOf(err))
}

Output:
503
true

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Internal("X", "x", errorx.WithStack())
	frames := errorx.StackOf(err)
	fmt.Println(len(frames) > 0)
}

Output:
true

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// Override default category (use sparingly — defaults are usually right).
	err := errorx.New("AIHUB_BUSINESS_RULE_VIOLATION",
		errorx.WithCategory(errorx.CategoryValidation),
	)
	fmt.Println(errorx.CategoryOf(err))
}

Output:
validation

package main

import (
	"errors"
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// WithCause preserves the underlying error for errors.Is / errors.As.
	cause := errors.New("redis: connection refused")
	err := errorx.Unavailable("CACHE_UNAVAILABLE", "缓存不可用",
		errorx.WithCause(cause),
	)
	fmt.Println(errors.Is(err, cause))
}

Output:
true

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.New("AIHUB_CUSTOM",
		errorx.WithGRPCCode("FailedPrecondition"),
	)
	fmt.Println(errorx.GRPCCodeOf(err))
}

Output:
FailedPrecondition

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// Override default HTTP status (use sparingly — prefer semantic constructors).
	err := errorx.New("AIHUB_PAYMENT_REQUIRED",
		errorx.WithHTTPStatus(402),
	)
	fmt.Println(errorx.HTTPStatusOf(err))
}

Output:
402

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.New("AIHUB_SKILL_NOT_FOUND",
		errorx.WithMessage("技能不存在"),
	)
	fmt.Println(err.Error())
}

Output:
技能不存在

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// Internal metadata — for logs/audit only, NOT returned to clients.
	err := errorx.NotFound("AIHUB_SKILL_NOT_FOUND", "技能不存在",
		errorx.WithMetadata("skill_id", "skill_001"),
		errorx.WithMetadata("project_id", "proj_001"),
		errorx.WithMetadata("raw_db_error", "record not found"),
	)
	md := errorx.MetadataOf(err)
	fmt.Println(md["skill_id"])
	fmt.Println(md["project_id"])
}

Output:
skill_001
proj_001

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// WithMetadataMap adds multiple metadata entries at once.
	err := errorx.Internal("AIHUB_DB_FAILED", "数据库失败",
		errorx.WithMetadataMap(map[string]any{
			"dsn":   "postgres://...",
			"query": "SELECT * FROM skills",
		}),
	)
	md := errorx.MetadataOf(err)
	fmt.Println(md["dsn"])
}

Output:
postgres://...

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// PublicMetadata is safe for HTTP/gRPC responses.
	// Metadata is for internal logs/audit only.
	err := errorx.Forbidden("IAM_PERMISSION_DENIED", "权限被拒绝",
		errorx.WithMetadata("raw_policy", "deny"),      // internal
		errorx.WithPublicMetadata("resource", "skill"), // public
		errorx.WithPublicMetadata("action", "delete"),  // public
	)
	fmt.Println(errorx.PublicMetadataOf(err))
}

Output:
map[action:delete resource:skill]

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.NotFound("AIHUB_SKILL_NOT_FOUND", "技能不存在",
		errorx.WithPublicMetadataMap(map[string]any{
			"resource": "skill",
			"name":     "demo-skill",
		}),
	)
	fmt.Println(errorx.PublicMetadataOf(err)["resource"])
}

Output:
skill

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Internal("AIHUB_FAILED", "失败",
		errorx.WithRequestID("req_abc123"),
	)
	fmt.Println(errorx.RequestIDOf(err))
}

Output:
req_abc123

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// Override default retryable. Use when business knows better than defaults.
	err := errorx.Internal("AIHUB_DB_TRANSACTION_FAILED", "数据库事务失败",
		errorx.WithRetryable(true),
	)
	fmt.Println(errorx.RetryableOf(err))
}

Output:
true

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// Override default severity for logx.
	err := errorx.New("AIHUB_DEGRADED",
		errorx.WithMessage("服务降级"),
		errorx.WithSeverity(errorx.SeverityWarn),
	)
	fmt.Println(errorx.SeverityOf(err))
}

Output:
warn

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	// Capture call stack for debugging. Only use for 5xx errors.
	err := errorx.Internal("AIHUB_INTERNAL_FAILED", "内部错误",
		errorx.WithStack(),
	)
	frames := errorx.StackOf(err)
	if len(frames) > 0 {
		fmt.Println("stack captured")
	}
}

Output:
stack captured

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	err := errorx.Internal("AIHUB_FAILED", "失败",
		errorx.WithTraceID("trace_xyz789"),
	)
	fmt.Println(errorx.TraceIDOf(err))
}

Output:
trace_xyz789

package main

import (
	"fmt"

	"github.com/aisphereio/kernel/errorx"
)

func main() {
	fmt.Println(errorx.SeverityOf(errorx.BadRequest("X", "x")))
	fmt.Println(errorx.SeverityOf(errorx.Internal("X", "x")))
	fmt.Println(errorx.SeverityOf(errorx.ClientClosed("X", "x")))
}

Output:
info
error
debug