server

import "github.com/infobloxopen/devedge-sdk/server"

type Config struct {
    // GRPCAddr is the TCP address to listen on (e.g. ":9090" or ":0"). Required.
    GRPCAddr string
    // HTTPAddr is the optional gateway address (e.g. ":8080"). Empty disables the HTTP gateway.
    HTTPAddr string
    // Rules is an OPTIONAL additive authz rule set. The generated Register<Service>
    // contributes each service's rules automatically (via AddRules), so the
    // generated path never needs this; set it only to merge in extra rules. The
    // rules feed both grpcauthz (enforcement) and the field-mask interceptor.
    Rules []authz.MethodRule
    // Authorizer is the pluggable decision point.
    // Defaults to authz.NewDevAuthorizer() (default-deny) if nil.
    Authorizer authz.Authorizer
    // PrincipalFunc derives the authz.Principal from each request (threaded to
    // grpcauthz.WithPrincipalFunc). nil → empty principal → every non-public
    // call is denied. Use grpcauthz.DevPrincipalFunc() in dev; a verified-token
    // function in production.
    PrincipalFunc grpcauthz.PrincipalFunc
    // Authenticator, when set, inserts the authentication interceptor BEFORE
    // authz. It verifies the request bearer (signature + iss/aud/exp) and
    // stashes the verified authz.Principal, which the authorizer reads via
    // authn.VerifiedPrincipal. PrincipalFunc defaults to authn.VerifiedPrincipal
    // when Authenticator is set. An invalid bearer is rejected with
    // codes.Unauthenticated (fail closed). Nil keeps the prior behavior.
    Authenticator authn.Authenticator
    // Interceptors are additional unary interceptors appended after the framework chain.
    Interceptors []grpc.UnaryServerInterceptor
    // HTTPHandlers mount net/http handlers on the HTTP server at path patterns,
    // alongside the gateway: OIDC provider endpoints, webhooks, a login UI, or
    // static assets. The /healthz and /readyz probes always win; a "/" handler
    // replaces the gateway catch-all. Requires HTTPAddr.
    HTTPHandlers []HTTPHandler
    // DeduplicationStore backs the idempotency interceptor. Defaults to an
    // in-memory store (10-minute TTL) when nil.
    DeduplicationStore middleware.DeduplicationStore
    // LROStore backs long-running operations (AIP-151). Defaults to an in-memory
    // store (1-hour TTL) when nil.
    LROStore lro.Store
    // Logger is the structured logger the default chain's middleware.LoggingUnary
    // writes one record per RPC to (trace-correlated, secret-redacted payloads at
    // Debug). Defaults to slog.Default() when nil.
    Logger *slog.Logger
    // ReadinessChecks is the list of readiness checks the server runs on every
    // /readyz probe and whenever it drives the gRPC health status. An empty slice
    // means "always ready". Each check is bounded by a 2s timeout.
    ReadinessChecks []health.Check
    // Resilience configures optional resilience policy interceptors inserted into
    // the default chain. server.New applies a 30-second request timeout when the
    // zero value is supplied; rate limiting and circuit breaking are opt-in (nil).
    Resilience ResilienceConfig
}

type ResilienceConfig struct {
    RequestTimeout   time.Duration
    PerMethodTimeout map[string]time.Duration
    RateLimiter      resilience.RateLimiter
    CircuitBreaker   resilience.CircuitBreaker
}

type HTTPHandler struct {
    Pattern string       // net/http ServeMux pattern (e.g. "/oauth/", "/keys", "/")
    Handler http.Handler
}

func New(cfg Config) (*Server, error)

chain := []grpc.UnaryServerInterceptor{
    middleware.RequestIDUnary(),
    middleware.ErrorMapperUnary(),
    middleware.TenantIDUnary(),
    grpcauthz.UnaryServerInterceptor("sdk", authzOpts...), // fail-closed; reads the LIVE accumulated rule set (Config.Rules + AddRules)
    middleware.FieldMaskUnarySource(...),                  // verb map derived from the live accumulated rule set
    etag.PreconditionUnary(),
    middleware.ReadMaskUnary(),                            // AIP-157 response field selection
    middleware.ValidateOnlyUnary(),                        // short-circuit validate_only requests
    middleware.DeduplicateUnary(cfg.DeduplicationStore),   // idempotency replay
}
chain = append(chain, cfg.Interceptors...)

func (s *Server) Serve(ctx context.Context) error

func (s *Server) GRPCServer() *grpc.Server

func (s *Server) RegisterGateway(fn func(context.Context, *runtime.ServeMux, *grpc.ClientConn) error)

func (s *Server) AddRules(rules ...authz.MethodRule)   // contribute authz rules (the generated Register<Service> calls this)
func (s *Server) RecordMethods(methods ...string)      // record registered FullMethods for the Serve-time gate
func (s *Server) GatewayMux() *runtime.ServeMux         // nil when no HTTP gateway
func (s *Server) Rules() []authz.MethodRule             // the accumulated set (Config.Rules + AddRules)
func (s *Server) GRPCAddr() string // actual bound addr after Serve (useful when GRPCAddr was ":0")
func (s *Server) HTTPAddr() string // actual bound gateway addr after Serve; "" when no gateway

// Cross-service references (F041) — the generated Register<Service> calls the first two for you:
func (s *Server) RecordReferences(refs ...reference.Reference)      // references this service declares
func (s *Server) RecordBatchTarget(resourceType string)            // THIS server serves BatchGet<Target> (co-located)
func (s *Server) RecordExternalReferenceTarget(resourceType string) // target served by ANOTHER process (split federation); the gateway resolves it
func (s *Server) References() []reference.Reference                 // the accumulated references

package main

import (
    "context"
    "log"
    "os/signal"
    "syscall"

    "github.com/infobloxopen/devedge-sdk/authz"
    "github.com/infobloxopen/devedge-sdk/authz/grpcauthz"
    "github.com/infobloxopen/devedge-sdk/server"

    "github.com/example/widget/widgetv1"
)

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()

    srv, err := server.New(server.Config{
        GRPCAddr: ":9090",
        HTTPAddr: ":8080",
        // No Rules: the generated registration contributes WidgetServiceAuthzRules
        // for you (Config.Rules is now only an optional additive override).
        Authorizer: authz.NewDevAuthorizer(authz.Grant{
            Tenant:   "t1",
            Subjects: []string{"group:admin"},
            Verbs:    []authz.Verb{"*"},
            Resource: "*",
        }),
        // Dev: derive the principal from request metadata so the grant above can
        // match (account-id → Tenant, groups → group:<name>). In production use a
        // PrincipalFunc backed by a verified token, never raw client headers.
        PrincipalFunc: grpcauthz.DevPrincipalFunc(),
    })
    if err != nil {
        log.Fatal(err)
    }

    // One-call CRUD wiring (generated by protoc-gen-svc): construct the generated
    // default handler over the repository, register it on gRPC + the HTTP gateway,
    // and contribute the service's authz rules. The boot-time completeness gate runs
    // at Serve. (For custom logic, embed WidgetServiceCRUDHandler, override the
    // methods you change, and use RegisterWidgetService(srv, h) instead.)
    if err := widgetv1.RegisterWidgetServiceWithRepository(srv, newWidgetRepository()); err != nil {
        log.Fatal(err)
    }

    log.Printf("gRPC %s  HTTP %s", srv.GRPCAddr(), srv.HTTPAddr())
    if err := srv.Serve(ctx); err != nil {
        log.Fatal(err)
    }
    log.Println("shut down cleanly")
}

# Allowed — identity matches the dev grant:
curl -s -X POST localhost:8080/v1/widgets \
  -H 'account-id: t1' -H 'groups: admin' \
  -d '{"name": "w1"}'

# Denied — no identity → empty principal → fail closed:
curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/v1/widgets/w1   # 403