DEV Community: Syukur

Implementing Dependency Injection By Testing gRPC Service Call

Syukur — Tue, 14 Apr 2026 04:13:33 +0000

Photo by Shruti Parthasarathy on Unsplash

Motivation

Need to test business logic that depends on gRPC call
Avoid coupling test with network, connection setup, and external services
Ensure tests are deterministic and fast

Scenario

Below is definition of ServiceV1 and its dependency

package service

type ServiceV1 struct{}

func NewServiceV1() ServiceV1 {
    return ServiceV1{}
}

Below is content of student_v1.proto, which defines request and response for student gRPC service.

syntax = "proto3";

option go_package = "../grpc/student";

package student;

message GetStudentRequest {
  int32 id = 1;
}

message GetStudentResponse {
  int32 id = 1;
}

service Student {
  rpc GetStudent (GetStudentRequest) returns (GetStudentResponse);
}

Function NewStudentGRPCService() creates gRPC client to student gRPC service.

func NewStudentGRPCService(
    addr string,
) (studentGRPCClient.StudentClient, error){
    client, err := grpc.NewClient(addr)
    if err != nil {
        return nil, err
    }

    return studentGRPCClient.NewStudentClient(client), nil
}

GetStudentV1() calls GetStudent gRPC request to student gRPC service.

func (s *ServiceV1) GetStudentV1(
    ctx context.Context,
    studentClientAddr string,
    id int32,
) (int32, error) {
    client, err := grpc.NewClient(studentClientAddr)
    if err != nil {
        return 0, err
    }

    studentGRPCClient := student.NewStudentClient(client)

    responseID, err := studentGRPCClient.GetStudent(ctx, &student.GetStudentRequest{
        Id: id,
    })
    if err != nil {
        return 0, err
    }

    return responseID.Id, nil
}

Let's create test for function above.

package service_test

type serviceProxy struct {
    svcV1 service.ServiceV1
}

func newServiceProxy(
) serviceProxy{
    svcV1 := service.NewServiceV1()
    return serviceProxy{
        svcV1: svcV1,
    }
}

func TestGetStudent(t *testing.T){
    cctx := context.Background()
    svcProxy := newServiceProxy()

    t.Run("success get student", func(t *testing.T) {
        resp, err := svcProxy.svcV1.GetStudentV1(cctx, "",1)
        assert.NoError(t, err)
        assert.Equal(t, 1, resp)
    })
}

It will return grpc: no transport security set error, because there is no live student gRPC server, does not matter student gRPC client address you are passing for GetStudentV1 argument, the test will always fail.

This gRPC service calls makes GetStudentV1() hard to test,
because it tightly coupled with student gRPC service by using
connection client on function body.

To make this less coupled, student gRPC server instantiation
must be done outside GetStudentV1() function, and
GetStudentV1() gRPC service call must be done using interface.

Solution

Note that gRPC code generates interface StudentClient and a concrete type studentClient that implements/has gRPC services. This allows us to replace real client with our own implementation for testing purposes.

If we dig to generated gRPC service code, note that NewStudentClient returns studentClient struct that implements/has GetStudent method. Thinking the same way, we create our own mock client that implements/has GetStudent method with same argument and return values implemented by studentClient.

type StudentGRPCMock struct{}

func NewStudentGRPCMock() *StudentGRPCMock{
    return &StudentGRPCMock{}
}

func (m *StudentGRPCMock) GetStudent(ctx context.Context, in *studentGRPCClient.GetStudentRequest, opts ...grpc.CallOption) (*studentGRPCClient.GetStudentResponse, error) {
    return &studentGRPCClient.GetStudentResponse{
        Id: 1,
    }, nil
}

Note that function body of GetStudent implemented by studentClient's generated code is different compared to StudentGRPCMock. This is valid interface definition because interface forces a type to have same arguments/signature and return types, without considering content of function body.

package service

type Service struct {
    studentGRPCClient student.StudentClient
}

func NewService(
    studentGRPCClient student.StudentClient,
) Service {
    return Service{
        studentGRPCClient: studentGRPCClient,
    }
}

package service_test

type serviceProxy struct {
    svc service.Service
    svcV1 service.ServiceV1
}

func newServiceProxy(
) serviceProxy{
    mockStudentClient := student.NewStudentGRPCMock()
    svc := service.NewService(mockStudentClient)

    svcV1 := service.NewServiceV1()
    return serviceProxy{
        svc: svc,
        svcV1: svcV1,
    }
}

After rewriting ServiceV1 to Service struct by injecting StudentClient interface, we are no longer depends on real gRPC connection to call GetStudent service. This approach is called dependency injection where dependencies are provided from outside instead of being created inside the function.

func (s *Service) GetStudent(
    ctx context.Context,
    id int32,
) (int32, error) {
    responseID, err := s.studentGRPCClient.GetStudent(ctx, &student.GetStudentRequest{
        Id: id,
    })
    if err != nil {
        return 0, err
    }

    return responseID.Id, nil
}

Let's update test file to verify that refactored GetSudent() is working.

package service_test

func TestGetStudent(t *testing.T){
    cctx := context.Background()
    svcProxy := newServiceProxy()

    t.Run("success get student", func(t *testing.T) {
        resp, err := svcProxy.svc.GetStudent(cctx, 1)
        assert.NoError(t, err)
        assert.Equal(t, 1, resp)
    })
}

Run go test -v -count=1 -timeout 30m -coverprofile=coverage.out ./service/... on terminal to test and generate test coverage for service package, followed by go tool cover -html=coverage.out to generate HTML file to visualize code coverage.

At this point, we've been succesfully test service/business logic that calls gRPC service by injecting gRPC interface instead of using actual gRPC connection.

Limitation

Mock implementation shows us fixed response. While this approach is sufficient for simple case, it becomes limiting when we want to test various cases and edge cases.

A more flexible approach is allows mock to define its behavior per test and cases.

Resource

Complete code for this article can be found here.

Making Sense Golang Worker Pattern

Syukur — Thu, 26 Feb 2026 10:37:17 +0000

Motivation

Imagine we are asked to insert 10000 rows to database by
calling repository.InsertStudentData() function.
Just iterate over rows. It sounds fine at first, but how long
it will take to completely insert them? What will likely happend
to computer resources?

Fine, we can use goroutine to run them concurrently.

Understanding Worker Pattern

Basically, worker pattern consist of 3 steps

Spawn workers
Publish task/job to workers
Collecting results

1. Spawn workers

Workers in this pattern are represented in function that runs
concurrently using goroutine. Look at snippet below.

{
    ...
    intNumWorkers := 3

    for w := 0; w < intNumWorkers; w++ {
        go InsertStudentData(ctx, tx, insertedStudentJobs, insertedStudentjobsErrCh)
    }
    ...
}

func InsertStudentData(ctx context.Context, tx *sql.Tx, data <-chan models.StudentItem, errCh chan<- error) {
    ...
}

This means the code will spawns 3 different workers where
each worker does not need to wait each other to finish its task.

Illustration of this step as follows.

2. Publish task/job to workers

As mentioned earlier, Because workers run concurrently and are
independent of each other, and because goroutines cannot
directly return values to their caller, channels are used
as a coordination mechanism for workers to pull jobs and
publish results safely.

Take a look of this snippet where a caller publishes
jobs to workers.

{
    ...
    numJobs := len(StudentItems)
    jobs := make(chan models.StudentItem, numJobs)

    for i := 0; i < numJobs; i++ {
        jobs <- StudentItems[i]
    }

    close(jobs)
    ...
}

func InsertStudentWorker(ctx context.Context, tx *sql.Tx, data <-chan models.StudentItem, errCh chan<- error) {
    for d := range data {
        err := repository.InsertStudentItemFromWorker(ctx, tx, d)
        ...
    }
}

Worker accepts a read-only channel argument (data <-chan models.StudentItem).
This means as task is availble on channel, whichever available worker
will recieves it. Recall that workers
are running concurrently, this means we don't care which worker
will pull task from caller.

Finally, we close jobs channel to prevent goroutine leak.

This illustration demonstrates second step.

3. Collecting results

Once worker finish its task, the result will be send to write-only channel.
Since caller knows how many jobs were published, it reads number of results
from the channel without caring which worker produces each one. Snippet below is enhancement
from above, where worker publishes its result to result channel, then
caller read from the stream.

{
    ...
    numJobs := len(StudentItems)
    jobs := make(chan models.StudentItem, numJobs)

    for i := 0; i < numJobs; i++ {
        jobs <- StudentItems[i]
    }

    close(jobs)

    // read from channel stream
    for j := 0; j < numJobs; j++ {
        err := <-jobsErrCh
        if err != nil {
            _ = tx.Rollback()
            return err
        }
    }
}

func InsertStudentWorker(ctx context.Context, tx *sql.Tx, data <-chan models.StudentItem, errCh chan<- error) {
    for d := range data {
        err := repository.InsertStudentItemFromWorker(ctx, tx, d)
        errCh <- err
    }
}

Illustration below demonstrates this step.

Exploring WebSocket Part 3: Handling Fragmentation

Syukur — Fri, 13 Feb 2026 03:03:58 +0000

What Is Fragmentation and Why We Care About It?

Imagine we have a stream of subtitle from a 10 minute video. Subtitle
is being render on client side in real time as video
playing through WebSocket connection. How the whole
subtitle sent successfuly to client?

If we answer just send whole subtitle, the answer is
less precise. Let's step back to previous article where
we discusses about payload length.

RFC states maximum payload length in single frame.
WebSocket RFC limits message payload in a single
frame, where it capped at 2^63 bytes. Consequently,
a frame with it's message payload exceeds 2^63 bytes
is non-compliant. To make it compliant,
that frame should comply fragmentation.

Fragmentation is a protocol to split complete WebSocket
message into multiple frames. For example, consider
a complete text message abcdefgh. We can send
that message as one complete text frame or multiple
text frames by apply fragmentation protocol. Number of
text frames is arbitrary in count, not in structure
during fragmentation. A compliant server must implements fragmentation rules correctly from
receives to assembles complete message, leaving no
room for protocol violation.

One valid fragmented sequence of abcdefgh looks like this:

Frame 1:
FIN = 0
Opcode = 1 (text)
Payload = "abc"

Frame 2:
FIN = 0
Opcode = 0 (continuation)
Payload = "def"

Frame 3:
FIN = 1
Opcode = 0 (continuation)
Payload = "gh"

Why first frame's FIN is 0 and last frame's FIN is 1?
Why other frame's opcode is 0 except first frame? What
about control frames?. We'll answer these questions
in next section.

Fragmentation Rules

This article focuses on direct client-server WebSocket
fragmentation rules as defined by RFC 6455 without
negotiated extensions or intermediaries (such as proxies
or message-transforming middlewares).

While RFC also defines considerations for extensions and
intermediaries, those topics are outside of this article.
The rules presented below apply to a baseline, RFC-compliant
WebSocket endpoint.

An unfragmented/complete message consists of a single frame with FIN bit set (FIN = 1) and an opcode other than 0
A fragmented message consists of single frame with FIN bit clear (FIN = 0) and an opcode other than 0, followed by zero or more frames with FIN bit clear and opcode set to 0, and terminated by single frame with FIN bit set and an opcode of 0
Control frames MAY be injected in the middle of fragmented message. Control frames themselves MUST NOT be fragmented
Message fragments MUST be delivered to the recipient in the order sent by the sender.
An endpoint MUST be capable of handling control frames in the middle of fragmented message.
A sender MAY create fragments of any size for non-control messages.

As a consequence of these rules, abcdefgh message may
be arranged as:

Case 1: 4 Frames without injected control frame during
fragmentation

Frame A:
FIN = 0
opcode = 1
message = `ab`

Frame B:
FIN = 0
opcode = 0
message = `cd`

Frame C:
FIN = 0
opcode = 0
message = `ef`

Frame D:
FIN = 1
opcode = 0
message = `gh`

This is valid fragmentation. Reciever/server begins buffering
message when it receives frame A, continues buffering frame B
and C, then assembles complete message upon receives frame D.

Case 2: 4 Frames without injected control frame, but middle
of fragmented message has invalid opcode

Frame A:
FIN = 0
opcode = 1
message = `ab`

Frame B:
FIN = 0
opcode = 1
message = `cd`

Frame C:
FIN = 0
opcode = 0
message = `ef`

Frame D:
FIN = 1
opcode = 0
message = `gh`

As consequence of rule #2, this sequence mark as invalid
fragmentation, because to opcode of frame B is not 0
(violates rule #2).

Case 3: 5 Frames with appearance of consecutive control frame
during fragmentation

Frame A:
FIN = 0
opcode = 1
message = `ab`

Frame B:
FIN = 1
opcode = 9
message = `X`

Frame C:
FIN = 1
opcode = 9
message = `X`

Frame D:
FIN = 0
opcode = 0
message = `cdef`

Frame E:
FIN = 1
opcode = 0
message = `gh`

This sequence is valid fragmentation. A compliant server must
begin buffering upon receives frame A, then respond to ping
message when receives frame B and C immediately (as required
by rule #3 and #4).

Server must not treat these control frames as part of whole
message and must not buffer them. Server continues to buffering
message upon receives frame D, and finalize whole message
when receives frame E (Rule #5).

Case 4: 4 Frames with opcode of middle fragmented frame is not
0

Frame A:
FIN = 0
opcode = 1
message = `ab`

Frame B:
FIN = 1
opcode = 1
message = `cd`

Frame C:
FIN = 0
opcode = 0
message = `ef`

Frame D:
FIN = 1
opcode = 0
message = `gh`

This case mark as invalid fragmentation, because opcode of
frame B is not 0 during fragmentation (violates rule #2).
The server must terminates connection immediately with protocol
error code upon receiving frame B before processing frame
C and D.

Case 5: 3 frames with opcode of final frame is not 0

Frame A:
FIN = 0
opcode = 1
message = `ab`

Frame B:
FIN = 0
opcode = 0
message = `cd`

Frame C:
FIN = 1
opcode = 1
message = `efgh`

This is invalid fragmentation sequence, because opcode of
final frame (frame C) is not set to 0 (violates rule #2)

Earlier on this article, we stated that number of frames
in fragmentation is arbitrary in count, not in structure.

Arbitrary in count demonstrated by case 1, where we
split whole message to different number of frames. Client
can choose number of frames freely as long as the fragmentation
rules are followed

Not arbitrary in structure demonstrated by case 2, 4, and 5
where those cases violates fragmentation rules - such as
using a non-zero opcode in the middle of fragmented message
or terminating fragmentation using non-continuation opcode.
These sequences are invalid, and resulting protocol error.

Given these rules, a compliant WebSocket endpoint effectively
operates as a small state machine while receiving frames.

state = IDLE
buffer = empty

on recieving frame:
    if frame is control frame:
        handle control frame immediately
        continue to next frame

    if state == IDLE:
        if FIN == 1 and opcode != 0:
            deliver message directly
        else if FIN == 0 and opcode != 0:
            state = FRAGMENTING
            start buffering
        else:
            return protocol error
    else if state == FRAGMENTING:
        if opcode != 0:
            return protocol error
        append message to buffer
        if FIN == 1:
            deliver reassembled message
            clear buffer
            state = IDLE

We'll refine this state machine to pseudocode along with
Golang implementation on next section.

Implementing Fragmentation

Fragmentation is a connection level state instead of frame level
logic. As shown by state machine on previous section, a fragmentation
compliant WebSocket endpoint must maintain connection scoped context
in order to process incoming frames correctly.

Specifically, such an endpoint must capable of:

Survive control frame interruptions

Control frame may appear in the middle of fragmentation. Endpoints
must be able to respond incoming control frame immediately without
breaking or resetting ongoing fragmentation process

Remember previous frames

Fragmentation rules expects endpoints to accept or reject frame
not only based on frame currently being processed, but also
prior frame. If a frame violates fragmentation rules given the
prior context, endpoint must close connection with protocol error.

In other words, a validity of WebSocket fragmentation is determined
by sequence of frames that being processes on same connection, instead
only verify single frame.

Let's translate state machine from previous section to pseudocode
as our blueprint, before jump to Go implementation.

if frame.opcode is control frame{
    handleControlFrame(frame)
    continue
}

if FIN == 0{
    if state == IDLE{
        if first frame opcode == 0{
            return protocol error
        }

        beginFragmentation(frame)
        state = FRAGMENTING
        initialOpcode = opcode
        continue read next frame
    }

    if frame.opcode != 0{
        return protocol error
    }

    bufferFragment(frame)
    continue read next frame
}else{
    if state == FRAGMENTING{
        if frame.opcode != 0{
            return protocol error
        }
        assembleFragment(frame)
        state = IDLE
        continue read next frame
    }

    if frame.opcode == 0{
        return protocol error
    }


    echo(frame)
}

Based on pseudocode above, fragmentation handled upon recieving
frame. Looking back on our previous code, handleRequest is
responsible to that action. Let's enhance previous code to handle
fragmentation and RFC compliant.

type WebSocketStatusCode uint16

var (
    StatusNormalClosure WebSocketStatusCode = 1000
    StatusProtocolError WebSocketStatusCode = 1002
    StatusMessageTooBig WebSocketStatusCode = 1009
)

type ws struct {
    conn   net.Conn
    reader *bufio.Reader
    writer *bufio.Writer

    assemblingRequest   bool
    initialBufferOpcode uint8
    bufferedRequest     []byte
}

type frame struct {
    opcode              uint8
    payloadIndicator    int64
    actualPayloadLength int64

    bigEndianPayloadFormat []byte

    isFin    bool
    isMasked bool
}

func (ws *ws) handleRequest() error {
    defer ws.conn.Close()

    for {
        frame, err := ws.readRequest(2)
        if err != nil {
            return err
        }

        if isControlFrame(frame.opcode) {
            if !frame.isFin || frame.actualPayloadLength > 125 {
                return ws.closeWithCode(frame, StatusProtocolError)
            }

            switch frame.opcode {
            case 8:
                return ws.closeWithCode(frame, StatusNormalClosure)
            case 9:
                err = ws.pong(frame)
                if err != nil {
                    return err
                }
                continue
            }
        }

        if !frame.isFin {
            if !ws.assemblingRequest {
                if frame.opcode == 0 {
                    return ws.closeWithCode(frame, StatusProtocolError)
                }

                ws.assemblingRequest = true
                ws.initialBufferOpcode = frame.opcode
                err = ws.bufferRequest(frame)
                if err != nil {
                    return err
                }

                continue
            }

            if frame.opcode != 0 {
                return ws.closeWithCode(frame, StatusProtocolError)
            }

            err = ws.bufferRequest(frame)
            if err != nil {
                return err
            }

            continue
        } else {
            if ws.assemblingRequest {
                if frame.opcode != 0 {
                    return ws.closeWithCode(frame, StatusProtocolError)
                }

                err = ws.assembleRequest(frame)
                if err != nil {
                    return err
                }
                continue
            }

            if frame.opcode == 0 {
                return ws.closeWithCode(frame, StatusProtocolError)
            }

            err = ws.echo(frame)
            if err != nil {
                return err
            }
        }
    }
}

func (ws *ws) assembleRequest(frame frame) error {
    switch ws.initialBufferOpcode {
    case 1:
        return ws.writeTextFrameResponse(frame)
    case 2:
        return ws.writeBinaryFrameResponse(frame)
    default:
        return ws.closeWithCode(frame, StatusProtocolError)
    }
}

func (ws *ws) closeWithCode(_ frame, closeCode WebSocketStatusCode) error {
    uCloseCode := uint16(closeCode)
    bufCloseCode := make([]byte, 2)
    binary.BigEndian.PutUint16(bufCloseCode, uCloseCode)

    responseFrame := []byte{
        0x88, // FIN + Close opcode
        0x02, // payload length = 2
        bufCloseCode[0],
        bufCloseCode[1],
    }

    _, err := ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return ws.conn.Close()
}

Fragmentation state handled in connection instead of frame.
WebSocket connection information and fragmentation state are store in ws struct. We enhance
the struct by adding assemblingRequest field to track fragmentation
state, initialBufferOpcode to save opcode of first frame
during fragmentation, which later server will determines final assembled
message is text or binary frame, and bufferedRequest to store valid
fragmented frames.

We've been demonstrated valid and invalid fragmentation sequences.
When server encounters invalid fragmented frame during fragmentation,
server close connection with specific error code. closeWithCode
terminates connection between server and client with specific close code.
Close code and its reason defined at section 7.4.1.

Code Refinement Spotlight

package main

import (
    "bufio"
    "crypto/sha1"
    "encoding/binary"
    "errors"
    "io"
    "log"
    "net"
    "strings"

    b64 "encoding/base64"
)

const (
    secWsKey = "Sec-WebSocket-Key"

    connHeaderKey = "Connection"
    connHeaderVal = "Upgrade"

    upgradeHeaderKey     = "Upgrade"
    upgradeConnHeaderVal = "websocket"
)

const (
    MAX_PAYLOAD_LENGTH = 262144
)

type WebSocketStatusCode uint16

var (
    StatusNormalClosure WebSocketStatusCode = 1000
    StatusProtocolError WebSocketStatusCode = 1002
    StatusMessageTooBig WebSocketStatusCode = 1009
)

var (
    ErrUnmaskedFrame = errors.New("client frame must be masked")
    ErrPayloadTooBig = errors.New("payload too big")
)

type ws struct {
    conn   net.Conn
    reader *bufio.Reader
    writer *bufio.Writer

    assemblingRequest   bool
    initialBufferOpcode uint8
    bufferedRequest     []byte
}

type frame struct {
    opcode              uint8
    payloadIndicator    int64
    actualPayloadLength int64

    bigEndianPayloadFormat []byte

    isFin    bool
    isMasked bool
}

func main() {
    port := ":8083"
    listener, err := net.Listen("tcp", port)
    if err != nil {
        log.Fatal(err)
    }

    log.Println("running on ", port)

    for {
        conn, err := listener.Accept()
        if err != nil {
            log.Fatalln(err)
        }

        go handshake(conn)
    }
}

func handshake(conn net.Conn) error {
    var secWsAccept string

    reader := bufio.NewReader(conn)

    for {
        header, err := reader.ReadString('\n')
        if err != nil && !errors.Is(err, io.EOF) {
            return err
        }

        if header == "\r\n" || header == "\n" {
            break
        }

        secWsAcceptVal, err := readHTTPUpgradeHeaderRequest(header)
        if err != nil {
            return err
        }

        if secWsAcceptVal != "" {
            secWsAccept = secWsAcceptVal
        }
    }

    writer := bufio.NewWriter(conn)

    upgradeResp := []string{
        "HTTP/1.1 101 Web Socket Protocol Handshake",
        "Server: go/echoserver",
        "Upgrade: WebSocket",
        "Connection: Upgrade",
        "Sec-WebSocket-Accept: " + secWsAccept,
        "", // required for extra CRLF
        "", // required for extra CRLF
    }

    _, err := writer.Write([]byte(strings.Join(upgradeResp, "\r\n")))
    if err != nil {
        return err
    }

    err = writer.Flush()
    if err != nil {
        return err
    }

    ws := ws{
        conn:   conn,
        reader: reader,
        writer: writer,
    }

    return ws.handleRequest()
}

// read HTTP upgrade request, returns Sec-WebSocket-Accept header
// value if header is Sec-WebSocket-Accept. Otherwise, checking
// other upgrade header defined at https://datatracker.ietf.org/doc/html/rfc6455#autoid-4
func readHTTPUpgradeHeaderRequest(header string) (string, error) {
    var secWsAccept string

    headerKeys := strings.Split(header, ":")
    headerKey := strings.TrimSpace(headerKeys[0])
    switch {
    case headerKey == upgradeHeaderKey:
        uUpgradeVal := strings.TrimSpace(headerKeys[1])

        if uUpgradeVal != upgradeConnHeaderVal {
            return "", errors.New("upgrade header value is not websocket")
        }

        return "", nil
    case strings.Contains(header, connHeaderKey):
        cConnVal := strings.TrimSpace(headerKeys[1])

        if cConnVal != connHeaderVal {
            return "", errors.New("conenection header value is not upgrade")
        }

        return "", nil
    case strings.Contains(header, secWsKey):
        sSecWsVal := strings.TrimSpace(headerKeys[1])

        secWsAccept = sSecWsVal + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

        sha := sha1.New()
        sha.Write([]byte(secWsAccept))
        encSecWsAccept := sha.Sum(nil)
        secWsAccept = b64.StdEncoding.EncodeToString(encSecWsAccept)

        return secWsAccept, nil
    }

    return "", nil
}

func (ws *ws) handleRequest() error {
    defer ws.conn.Close()

    for {
        frame, err := ws.readRequest(2)
        if err != nil {
            return err
        }

        // beginning of fragmentation
        if isControlFrame(frame.opcode) {
            if !frame.isFin || frame.actualPayloadLength > 125 {
                return ws.closeWithCode(frame, StatusProtocolError)
            }

            switch frame.opcode {
            case 8:
                return ws.closeWithCode(frame, StatusNormalClosure)
            case 9:
                err = ws.pong(frame)
                if err != nil {
                    return err
                }
                continue
            }
        }

        if !frame.isFin {
            if !ws.assemblingRequest {
                if frame.opcode == 0 {
                    return ws.closeWithCode(frame, StatusProtocolError)
                }

                ws.assemblingRequest = true
                ws.initialBufferOpcode = frame.opcode
                err = ws.bufferRequest(frame)
                if err != nil {
                    return err
                }

                continue
            }

            if frame.opcode != 0 {
                return ws.closeWithCode(frame, StatusProtocolError)
            }

            err = ws.bufferRequest(frame)
            if err != nil {
                return err
            }

            continue
        } else {
            if ws.assemblingRequest {
                if frame.opcode != 0 {
                    return ws.closeWithCode(frame, StatusProtocolError)
                }

                err = ws.assembleRequest(frame)
                if err != nil {
                    return err
                }
                continue
            }

            if frame.opcode == 0 {
                return ws.closeWithCode(frame, StatusProtocolError)
            }

            err = ws.echo(frame)
            if err != nil {
                return err
            }
        }
    }
}

func (ws *ws) echo(frame frame) error {
    switch frame.opcode {
    case 1:
        return ws.writeTextFrameResponse(frame)
    case 2:
        return ws.writeBinaryFrameResponse(frame)
    case 8:
        return ws.closeWithCode(frame, StatusNormalClosure)
    case 9:
        return ws.pong(frame)
    case 10:
    }
    return nil
}

func (ws *ws) assembleRequest(frame frame) error {
    switch ws.initialBufferOpcode {
    case 1:
        return ws.writeTextFrameResponse(frame)
    case 2:
        return ws.writeBinaryFrameResponse(frame)
    default:
        return ws.closeWithCode(frame, StatusProtocolError)
    }
}

func (ws *ws) writeBinaryFrameResponse(_ frame) error {
    return nil
}

func (ws *ws) resetFragmentation() {
    ws.assemblingRequest = false
    ws.bufferedRequest = []byte{}
    ws.initialBufferOpcode = 0
}

func isControlFrame(opcode uint8) bool {
    return opcode == 0x8 || opcode == 0x9 || opcode == 0xA
}

func (ws *ws) bufferRequest(frame frame) error {
    requestPayload, err := ws.readPayload(frame)
    if err != nil {
        return err
    }

    bufferAvailable := len(ws.bufferedRequest)+int(len(requestPayload)) <= MAX_PAYLOAD_LENGTH

    if !bufferAvailable {
        return ws.closeWithCode(frame, StatusMessageTooBig)
    }

    ws.bufferedRequest = append(ws.bufferedRequest, requestPayload...)

    ws.assemblingRequest = true

    return nil
}

func (ws *ws) readRequest(requestSize int) (frame, error) {
    header := make([]byte, requestSize)
    _, err := io.ReadFull(ws.reader, header)
    if err != nil {
        return frame{}, err
    }

    fin := (header[0] & 0x80) != 0
    opcode := header[0] & 0xf

    payloadLengthIndicator := header[1] & 0x7f
    isMasked := header[1]&0x80 != 0

    if !isMasked {
        return frame{}, ErrUnmaskedFrame
    }

    var actualPayloadLength uint64

    frame := frame{}

    switch {
    case payloadLengthIndicator < 126:
        actualPayloadLength = uint64(payloadLengthIndicator)
    case payloadLengthIndicator == 126:
        actualPayloadByte := make([]byte, 2)

        _, err = io.ReadFull(ws.reader, actualPayloadByte)
        if err != nil {
            return frame, err
        }

        actualPayloadLength = uint64(binary.BigEndian.Uint16(actualPayloadByte))
        frame.bigEndianPayloadFormat = actualPayloadByte

    case payloadLengthIndicator == 127:
        actualPayloadByte := make([]byte, 8)

        _, err = io.ReadFull(ws.reader, actualPayloadByte)
        if err != nil {
            return frame, err
        }

        actualPayloadLength = uint64(binary.BigEndian.Uint64(actualPayloadByte))

        if actualPayloadLength > MAX_PAYLOAD_LENGTH {
            return frame, errors.New("payload too big")
        }

        frame.bigEndianPayloadFormat = actualPayloadByte
    }

    frame.isFin = fin
    frame.opcode = opcode
    frame.isMasked = isMasked
    frame.payloadIndicator = int64(payloadLengthIndicator)
    frame.actualPayloadLength = int64(actualPayloadLength)
    return frame, nil
}

func (ws *ws) writeTextFrameResponse(frame frame) error {
    responseByte, err := ws.readPayload(frame)
    if err != nil {
        return err
    }

    if len(ws.bufferedRequest) != 0 {
        asembledResponse := []byte(ws.bufferedRequest)
        asembledResponse = append(asembledResponse, responseByte...)

        if len(responseByte) >= MAX_PAYLOAD_LENGTH {
            return ws.closeWithCode(frame, StatusMessageTooBig)
        }

        responseByte = asembledResponse
    }

    outOpcode := frame.opcode
    if ws.assemblingRequest {
        outOpcode = ws.initialBufferOpcode
    }

    if len(responseByte) <= 125 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | outOpcode
        responseFrame[1] = byte(len(responseByte))

        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }
    }

    if len(responseByte) >= 126 && len(responseByte) <= 65535 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | outOpcode
        responseFrame[1] = 0x7e

        actualPayloadFrameByte := make([]byte, 2)

        binary.BigEndian.PutUint16(actualPayloadFrameByte, uint16(len(responseByte)))
        responseFrame = append(responseFrame, actualPayloadFrameByte...)
        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }

    }

    if len(responseByte) >= 65536 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | outOpcode
        responseFrame[1] = 0x7f

        actualPayloadFrameByte := make([]byte, 8)

        binary.BigEndian.PutUint64(actualPayloadFrameByte, uint64(len(responseByte)))
        responseFrame = append(responseFrame, actualPayloadFrameByte...)
        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

func (ws *ws) closeWithCode(_ frame, closeCode WebSocketStatusCode) error {
    uCloseCode := uint16(closeCode)
    bufCloseCode := make([]byte, 2)
    binary.BigEndian.PutUint16(bufCloseCode, uCloseCode)

    responseFrame := []byte{
        0x88, // FIN + Close opcode
        0x02, // payload length = 2
        bufCloseCode[0],
        bufCloseCode[1],
    }

    _, err := ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return ws.conn.Close()
}

func (ws *ws) pong(frame frame) error {
    responseData, err := ws.readPayload(frame)
    if err != nil {
        return err
    }

    responseFrame := make([]byte, 2+len(responseData))
    responseFrame[0] = 0x8a
    responseFrame[1] = byte(len(responseData))
    copy(responseFrame[2:], responseData)
    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    return ws.writer.Flush()
}

func (ws *ws) readPayload(frame frame) ([]byte, error) {
    if !frame.isMasked {
        return nil, ErrUnmaskedFrame
    }

    maskingKey := make([]byte, 4)
    _, err := io.ReadFull(ws.reader, maskingKey)
    if err != nil {
        return nil, err
    }

    validPayloadLength := frame.actualPayloadLength >= 0 && frame.actualPayloadLength <= int64(MAX_PAYLOAD_LENGTH)

    if !validPayloadLength {
        return nil, ErrPayloadTooBig
    }

    n := int(frame.actualPayloadLength)
    requestData := make([]byte, n)
    _, err = io.ReadFull(ws.reader, requestData)
    if err != nil {
        return nil, err
    }

    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    return requestData, nil
}

We will breakdown code refinements on following subsections

Fragmentation State Tracking

Before Refinement:

Treats frame individually, without knowing prior frame on same
connection.

After Refinement:

Server stores previous frame information if client's request contains fragmentation state.

Why It Matters:

Fragmentation is a protocol mechanism that forces an endpoint to
retain state accross multiple frames. It cannot be enforced by handling
single frame in isolation. Validity of fragmentation state depends on earlier frame on the same connection.

For example:

An opcode 0x0 is invalid unless endpoint enters fragmentation

An opcode 0x1 or 0x2 is invalid if endpoint receives in the
middle of fragmentation

Without connection-scoped validation, an endpoint cannot determine
whether incoming request is valid continuation request or
violates fragmentation rules.

Changes On This Article:

Refined handleRequest() to handle fragmentation rules defined by RFC. Additionally, introduces isFin field at frame struct to detect FIN bit. Additionally, added assemblingRequest, initialBufferOpcode, and bufferedRequest onws` struct to track fragmentation state.

Buffer Fragmented Frames

Before Refinement:

Echoes request immediately without retaining prior frame information.

After Refinement:

Buffer request message if connection enters fragmentation state

Why It Matters:

Endpoint stores/buffers incoming frames until final frame (FIN=1)
arrives. Before it arrives, endpoint must not:

Deliver partial messages to client.
Interprets buffered text/binary messages.
Apply application-level logic.

Buffering ensures that:

Message boundaries are preserved
UTF-8 validation for text frame can be applied to complete message.
Oversized messages can be rejected before final message assembly.

Changes On This Article:

Introduces ws.bufferRequest function to buffer request message
if connection enters fragmentation state.

Protocol Violation Handling

Before Refinement:

Previous code only return 1000 status code (normal closure) by default,
ignores status code related to protocol violation. Fragmentation
rules require more specific status code including protocol error
or message too large that endpoint unable to handle.

After Refinement:

Uses defined status code related to protocol
violation such as protocol error or message too big

Why It Matters:

RFC 6455 defines protocol violations as connection-fatal errors. This
means, whenever fragmentation rules are violated, endpoint must terminates
connection with client.

Continuing fragmentation after violation risks:

Whole message misinterpretation.
Accepting attacker-controlled frame sequence.
Desynchronizing frame boundaries.

Changes On This Article:

Replaces ws.close() with ws.closeWithCode(),
which closes WebSocket connection between client and
server. Additionally, the function sends
RFC defined status code as connection termination reason

Control Frame Interleaving

Before Refinement:

Control frame treated like normal data or simply ignored

After Refinement:

Control frame handled immediately and never affected fragmentation
state

Why It Matters:

Control frames are allowed to appear at any point during fragmentation.
They are not part of message and must not taking part of
message assembling.
Endpoint must handle them immediately at the time when control frame appears,
and must not treat control frame as part of client's message

Changes On This Article:

Added isControlFrame() to detect whether incoming frame is control
frame or not. It called before fragmentation rules applied.

Contextual Frame Validity

Before Refinement:

Handles single frame immediately and ignores previous frame

After Refinement:

Preserves prior frame state including first frame opcode
and fragmentation state tracking.

Why It Matters:

As a consequence of fragmentation rules, endpoint must retain previous
frame state to determine whether current frame is valid. For example:

An continuation opcode 0x0 is invalid if no fragmentation is active on the connection.
A text frame or binary frame is invalid if fragmentation is active.
A fragmented control frame is always invalid

Changes On This Article:

Added assemblingRequest to track fragmentation state and initialBufferOpcode
to preserve opcode of first frame.

Closing Thought

RFC states maximum payload length of a single frame at 2^63 bytes.
A server that complies RFC must be able to handle frame that exceeds
the maximum payload length. To answer this limitation, a server must
follow fragmentation protocol.

Fragmentation is a protocol that splits WebSocket message into multiple
frames. The frames are abritrary in number, but not in structure. In other
words, we can split single frame to 3, 4, or 5 frames, but their order
must not be change by applying opcode rules and preserving continuation semantics.

Fragmentation is connection level instead of frame level logic. This means
that a compliant server must be able to tracks and checks prior frame to
determine whether incoming request is valid fragmentation.

At the end of this article, we've been enhanced our previous code
by not only handles extended payload length, but also tracks
fragmentation state on connection level.

Exploring WebSocket Part 2: Handling Extended Payload Length

Syukur — Tue, 23 Dec 2025 04:33:02 +0000

Recap From Previous Article

On previous article about creating minimal working websocket server, we've been explored creating handshake, create client request, walkthrough WebSocket frame format, and echoed client request.

Article Outline

At this moment, we're going to refine our previous code to be more RFC 6455 compliant, specially about payload length frame fragment. We'll still stick to RFC 6455 focusing on payload length, discussing network byte order, and some code refinements besides payload length to be more serious engineering.

Why Correctness Matters? It Already Works!

Building minimal working code is fine for learning, but it is not enough - specially when it use on real world client such as our web browser or cloud services that use WebSocket as their way to communicate with their clients. Those real world technologies expect strict RFC 6455 compliance. And remember: just because it works does not mean it is correct. Small request handling deviations such as incorrect payload length encoding or missing mask enforcement might break compability or lead to undefined behavior. Correctness ensures that our server interoperates reabliy with any standard compliance.

What Was Missing Then?

Section 5.2 of RFC 6455 explains payload length. It says

The length of the "Payload data", in bytes: if 0-125, that is the
payload length. If 126, the following 2 bytes interpreted as a
16-bit unsigned integer are the payload length. If 127, the
following 8 bytes interpreted as a 64-bit unsigned integer (the
most significant bit MUST be 0) are the payload length. Multibyte
length quantities are expressed in network byte order. Note that
in all cases, the minimal number of bytes MUST be used to encode
the length, for example, the length of a 124-byte-long string
can't be encoded as the sequence 126, 0, 124. The payload length
is the length of the "Extension data" + the length of the
"Application data". The length of the "Extension data" may be
zero, in which case the payload length is the length of the
"Application data".

In english, it says

Payload-length fragment does not always represent actual request length. It just a flag/signal where you MUST read actual payload length.

For example:

If client sents payload that has length exactly 64 bytes long, then value of payload length fragment is 64.
If client sents payload that has exactly 126 bytes long, then server MUST read next 2 bytes to capture request payload length instead of read payload length fragment.
If client sents payload that has length exactly 256 bytes long, then server MUST read next 8 bytes to capture request payload length.

In short:

If request length < 125: actual payload length is payload length fragment itself
If request length == 126: next 2 bytes encode actual payload length, server MUST NOT treat payload-length fragment as actual payload length; it MUST instead read extended payload-length fragment
If request length == 127: next 8 bytes encode actual payload length, server MUST NOT treat payload-length fragment as actual payload length; it MUST instead read extended payload-length fragment

Let's flashback what we've done previously where we built server that echoes client request.

func (ws *ws) readRequest(requestSize int) (frame, error) {
    data := make([]byte, requestSize)
    _, err := ws.reader.Read(data)
    if err != nil {
        return frame{}, err
    }

    opcode := data[0] & 0xf
    payloadLength := data[1] & 0x7f

    return frame{
        opcode:        opcode,
        payloadLength: int(payloadLength),
    }, nil
}

// writeTextFrameResponse echoes server response as same as
// client request. This works normally when client
// request length is < 126
func (ws *ws) writeTextFrameResponse(frame frame) error {
    // read masking key where masking key located
    // 3rd - 6th byte of request, first 2 already read
    // to retrieve opcode and payload length.
    maskingKey := make([]byte, 4)
    _, err := ws.reader.Read(maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.payloadLength)
    _, err = ws.reader.Read(requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    responseByte := []byte(requestData)

    responseFrame := make([]byte, 2)
    responseFrame[0] = 0x80 | frame.opcode
    responseFrame[1] = byte(len(responseByte))
    responseFrame = append(responseFrame, responseByte...)

    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

readRequest function reads payload length fragment but it does not read actual payload length. The problem is when frame read by writeTextFrameResponse, which only valid if payload length is < 125. If client sents request where it's payload is == 126, server will act with undefined behavior because when request reaches this function. Server will interprets next 4 bytes as masking key, while in fact next 2 bytes are extended payload length/actual payload length, then next 4 bytes from actual payload length are masking key.

    maskingKey := make([]byte, 4)
    _, err := ws.reader.Read(maskingKey)
    if err != nil {
        return err
    }

server will read next 4 bytes as masking key. That is not correct, because RFC states if request payload length is exactly 126, next 2 bytes are actual payload length, and masking key is next 4 bytes from actual payload length. If we enforce request server to echo client's request, client will close connection with server immediately because server does not handle request frame correctly.

Network Byte Order

Section 5.2 explicitly states

Multibyte length quantities are expressed in network byte order.

What is network byte order and why we must follow this rule?

Network byte order is a convention that defines data arrangement when a device transfer data across a network, and it is always in big-endian.

Even your computer stores data in little-endian arrangement, when transfering data throughout network protocol (WebSocket, HTTP, TCP), they will rearrange in big-endian arrangement. Here is difference between big-endian and little-endian arragement.

Big-endian: put largest byte (leftmost in order) first over the network
Little-endian: put smallest byte (rightmost in order) first over the network

For example, if we have 0x12345678 and let's say we have x that stores the bytes in either big-endian or little-endian

x in big-endian format is 0x12345678
x in little-endian format is 0x78563412

This detail plays significant role in WebSocket extended payload length fragment which always uses big-endian encoding.

If payload-length fragment == 126: next 2 bytes are actual payload length in big-endian arrangement
If payload-length fragment == 127: next 8 bytes are actual payload length in big-endian arrangement

It might be trivial at first glance, but this arrangement is prominent for WebSocket server. Let's use our echoing WebSocket server as example.

Consider a client sends a request with payload length is exactly 256 bytes :

Payload-length fragment: 0x7F (because 256 bytes payload length requires 16-bit payload extended length as actual payload length)
Extended payload-length fragment: 0x1 0x0

If we mistakenly encode extended payload-length in little-endian (0x0 0x1) the receiver interprets as 1 byte which corruputs the entire frame encoding.

Handle Extended Payload Length Properly

Now we are understand actual payload length, network byte order, and big-endian concept, it is our time to handle extended payload length properly. Let's begin with current readRequest function which accepts client's request and return request frame.

// Previous simplified version (for demonstration only)
func (ws *ws) readRequest(requestSize int) (frame, error) {
    data := make([]byte, requestSize)
    _, err := ws.reader.Read(data)
    if err != nil {
        return frame{}, err
    }

    opcode := data[0] & 0xf
    payloadLength := data[1] & 0x7f

    return frame{
        opcode:        opcode,
        payloadLength: int(payloadLength),
    }, nil
}

Earlier, our readRequest function only reads first 2 bytes and ignores additional bytes. Let's refactor that function to accept payload-length fragment defined by RFC 6455 that:

reads opcode
reads the mask bit
reads payload-length fragment (the indicator that tells us the actual payload-length is inline, next 2 bytes or next 8 bytes)
reads additional bytes as actual payload-length (next 2 or 8 bytes)
returns metadata needed to read payload safely

func (ws *ws) readRequest(requestSize int) (frame, error) {
    data := make([]byte, requestSize)
    _, err := io.ReadFull(ws.reader, data)
    if err != nil {
        return frame{}, err
    }

    var actualPayloadLength int64

    opcode := data[0] & 0xf
    payloadIndicator := data[1] & 0x7f
    isMasked := data[1]&0x80 != 0

    frame := frame{}

    // read payload length frame
    switch {
    case payloadIndicator < 126:
        actualPayloadLength = int64(payloadIndicator)
    case payloadIndicator == 126:
        // actual payload length is next 2 byte
        actualPayloadByte := make([]byte, 2)

        _, err := io.ReadFull(ws.reader, actualPayloadByte)
        if err != nil {
            return frame, err
        }

        actualPayloadLength = int64(binary.BigEndian.Uint16(actualPayloadByte))
    case payloadIndicator == 127:
        // actual payload length is next 8 byte
        actualPayloadByte := make([]byte, 8)

        _, err := io.ReadFull(ws.reader, actualPayloadByte)
        if err != nil {
            return frame, err
        }

        actualPayloadLength = int64(binary.BigEndian.Uint64(actualPayloadByte))
    }

    frame.opcode = opcode
    frame.payloadIndicator = int64(payloadIndicator)
    frame.actualPayloadLength = actualPayloadLength
    frame.isMasked = isMasked
    return frame, nil
}

Note: requestSize is kept for simplicity since our earlier code used it. A proper WebSocket frame reader always reads exactly 2 bytes first.

Notice changes we've made on refactored version compared to previous:

We defined payloadIndicator, which is a flag that tells us where is actual payload-length.
switch statment that compares payloadIndicator against payload-length fragment defined by RFC 6455.
We handled each payload-length fragment based on RFC 6455 payload-length definition. We use io.ReadFull to read n next bytes if payload-length fragment is either 126 or 127.
We decoded actual payload length using binary.BigEndian, because RFC 6455 requires all multibytes values transmitted in network byte order.
We use actualPayloadLength to store actual payload length whose value is decoded actual payload length (converted from big-endian bytes into an int64)

Echoing Request Back Correctly

Let's step back to previous writeTextFrameResponse that echoes client request

// writeTextFrameResponse echoes server response as same as
// client request. This works normally when client
// request length is < 126
func (ws *ws) writeTextFrameResponse(frame frame) error {
    // read masking key where masking key located
    // 3rd - 6th byte of request, first 2 already read
    // to retrieve opcode and payload length.
    maskingKey := make([]byte, 4)
    _, err := ws.reader.Read(maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.payloadLength)
    _, err = ws.reader.Read(requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    responseByte := []byte(requestData)

    responseFrame := make([]byte, 2)
    responseFrame[0] = 0x80 | frame.opcode
    responseFrame[1] = byte(len(responseByte))
    responseFrame = append(responseFrame, responseByte...)

    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

Our old writeTextFrameResponse explicitly said that it only handles request that length is < 126. Now let's refactor that function expects:

Close connection immediately when frame is not masked
Close conenction immediately when request payload length overloads server capacity
Calculates response size before build response frame on server instead of reflecting request size
Build response frame based on response size

Here is writeTextFrameResponse revision that tailored expectations above:

const (
    MAX_PAYLOAD_LENGTH = 262144
)

func (ws *ws) writeTextFrameResponse(frame frame) error {
    if !frame.isMasked {
        return ws.close(frame)
    }

    if frame.actualPayloadLength < 0 || frame.actualPayloadLength > MAX_PAYLOAD_LENGTH {
        return ws.close(frame)
    }

    maskingKey := make([]byte, 4)
    _, err := io.ReadFull(ws.reader, maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.actualPayloadLength)
    _, err = io.ReadFull(ws.reader, requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    responseByte := []byte(requestData)

    if len(responseByte) <= 125 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | frame.opcode
        responseFrame[1] = byte(len(responseByte))

        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }
    }

    if len(responseByte) >= 126 && len(responseByte) <= 65535 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | frame.opcode
        responseFrame[1] = 0x7e

        actualPayloadFrameByte := make([]byte, 2)

        binary.BigEndian.PutUint16(actualPayloadFrameByte, uint16(len(responseByte)))
        responseFrame = append(responseFrame, actualPayloadFrameByte...)
        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }

    }

    if len(responseByte) >= 65536 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | frame.opcode
        responseFrame[1] = 0x7f

        actualPayloadFrameByte := make([]byte, 8)

        binary.BigEndian.PutUint64(actualPayloadFrameByte, uint64(len(responseByte)))
        responseFrame = append(responseFrame, actualPayloadFrameByte...)
        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

func (ws *ws) close(frame frame) error {
    if !frame.isMasked {
        ws.conn.Close()
        return errors.New("frame MUST be masked")
    }

    responseFrame := []byte{
        0x88, // FIN + Close opcode
        0x02, // payload length = 2
        0x03, 0xE8, // close code 1000 in network byte order
    }

    _, err := ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    return ws.writer.Flush()
}

Let's walkthrough what we've done:

We close connection against client if request payload is not masked.
We prevent DDoS by checking incoming request length.
Read payload mask is unchanged
Now we are using actualPayloadLength to iterate over request payload instead of payloadLength. On previous version, using payloadLength to iterate over request payload is valid, because we handled payload length fragment that has value <= 125. Since we are handling 126 and 127 payload length fragment, we use extended/actual payload length stored on 2 next byte after masking key for 126 payload length fragment and stored on 8 next bytes after masking key for 127 payload length fragment
Now we build response frame based on their payload-length fragment. Don't forget that RFC states we must arrange extended payload length in big-endian arragement. Notice we are using binary.BigEndian.PutUint16 and binary.BigEndian.PutUint64. Those functions is to build big-endian from actual payload length. The arrangement follows Section 5.2.
Proper closing connection against client if request is not masked using close function. Remember that server MUST NOT its response.

Complete Code:

package main

import (
    "bufio"
    "crypto/sha1"
    "encoding/binary"
    "errors"
    "io"
    "log"
    "net"
    "strings"

    b64 "encoding/base64"
)

const (
    secWsKey = "Sec-WebSocket-Key"

    connHeaderKey = "Connection"
    connHeaderVal = "Upgrade"

    upgradeHeaderKey     = "Upgrade"
    upgradeConnHeaderVal = "websocket"
)

const (
    MAX_PAYLOAD_LENGTH = 262144
)

func main() {
    port := ":8083"
    listener, err := net.Listen("tcp", port)
    if err != nil {
        log.Fatal(err)
    }

    log.Println("running on ", port)

    for {
        conn, err := listener.Accept()
        if err != nil {
            log.Fatalln(err)
        }

        go handshake(conn)
    }
}

func handshake(conn net.Conn) error {
    var secWsAccept string

    reader := bufio.NewReader(conn)

    for {
        header, err := reader.ReadString('\n')
        if err != nil && !errors.Is(err, io.EOF) {
            return err
        }

        if header == "\r\n" || header == "\n" {
            break
        }

        secWsAcceptVal, err := readHTTPUpgradeHeaderRequest(header)
        if err != nil {
            return err
        }

        if secWsAcceptVal != "" {
            secWsAccept = secWsAcceptVal
        }
    }

    writer := bufio.NewWriter(conn)

    upgradeResp := []string{
        "HTTP/1.1 101 Web Socket Protocol Handshake",
        "Server: go/echoserver",
        "Upgrade: WebSocket",
        "Connection: Upgrade",
        "Sec-WebSocket-Accept: " + secWsAccept,
        "", // required for extra CRLF
        "", // required for extra CRLF
    }

    _, err := writer.Write([]byte(strings.Join(upgradeResp, "\r\n")))
    if err != nil {
        return err
    }

    err = writer.Flush()
    if err != nil {
        return err
    }

    ws := ws{
        conn:   conn,
        reader: reader,
        writer: writer,
    }

    return ws.handleRequest()
}

// read HTTP upgrade request, returns Sec-WebSocket-Accept header
// value if header is Sec-WebSocket-Accept. Otherwise, checking
// other upgrade header defined at https://datatracker.ietf.org/doc/html/rfc6455#autoid-4
func readHTTPUpgradeHeaderRequest(header string) (string, error) {
    var secWsAccept string

    headerKeys := strings.Split(header, ":")
    headerKey := strings.TrimSpace(headerKeys[0])
    switch {
    case headerKey == upgradeHeaderKey:
        uUpgradeVal := strings.TrimSpace(headerKeys[1])

        if uUpgradeVal != upgradeConnHeaderVal {
            return "", errors.New("upgrade header value is not websocket")
        }

        return "", nil
    case strings.Contains(header, connHeaderKey):
        cConnVal := strings.TrimSpace(headerKeys[1])

        if cConnVal != connHeaderVal {
            return "", errors.New("conenection header value is not upgrade")
        }

        return "", nil
    case strings.Contains(header, secWsKey):
        sSecWsVal := strings.TrimSpace(headerKeys[1])

        secWsAccept = sSecWsVal + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

        sha := sha1.New()
        sha.Write([]byte(secWsAccept))
        encSecWsAccept := sha.Sum(nil)
        secWsAccept = b64.StdEncoding.EncodeToString(encSecWsAccept)

        return secWsAccept, nil
    }

    return "", nil
}

type ws struct {
    conn   net.Conn
    reader *bufio.Reader
    writer *bufio.Writer
}

func (ws *ws) handleRequest() error {
    defer ws.conn.Close()

    for {
        frame, err := ws.readRequestRFCCompliant(2)
        if err != nil {
            return err
        }

        switch frame.opcode {
        case 1:
            err := ws.writeTextFrameResponseRFCCompliant(frame)
            if err != nil {
                return err
            }
        case 2:
            log.Println("binary frame")
        case 8:
            return ws.close(frame)
        case 9:
            ws.pong(frame)
        default:
            ws.close(frame)
        }
    }
}

func (ws *ws) readRequestRFCCompliant(requestSize int) (frame, error) {
    data := make([]byte, requestSize)
    _, err := io.ReadFull(ws.reader, data)
    if err != nil {
        return frame{}, err
    }

    var actualPayloadLength int64

    opcode := data[0] & 0xf
    payloadIndicator := data[1] & 0x7f
    isMasked := data[1]&0x80 != 0

    frame := frame{}

    // read payload length frame
    switch {
    case payloadIndicator < 126:
        actualPayloadLength = int64(payloadIndicator)
    case payloadIndicator == 126:
        // actual payload length is next 2 byte
        actualPayloadByte := make([]byte, 2)

        _, err := io.ReadFull(ws.reader, actualPayloadByte)
        if err != nil {
            return frame, err
        }

        actualPayloadLength = int64(binary.BigEndian.Uint16(actualPayloadByte))
        frame.bigEndianPayloadFormat = append(frame.bigEndianPayloadFormat, actualPayloadByte...)
    case payloadIndicator == 127:
        // actual payload length is next 8 byte
        actualPayloadByte := make([]byte, 8)

        _, err := io.ReadFull(ws.reader, actualPayloadByte)
        if err != nil {
            return frame, err
        }

        actualPayloadLength = int64(binary.BigEndian.Uint64(actualPayloadByte))
        frame.bigEndianPayloadFormat = actualPayloadByte
    }

    frame.opcode = opcode
    frame.payloadIndicator = int64(payloadIndicator)
    frame.actualPayloadLength = actualPayloadLength
    frame.isMasked = isMasked
    return frame, nil
}

func (ws *ws) writeTextFrameResponseRFCCompliant(frame frame) error {
    if !frame.isMasked {
        return ws.close(frame)
    }

    if !(frame.actualPayloadLength >= 0 && frame.actualPayloadLength <= MAX_PAYLOAD_LENGTH) {
        return ws.close(frame)
    }

    maskingKey := make([]byte, 4)
    _, err := io.ReadFull(ws.reader, maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.actualPayloadLength)
    _, err = io.ReadFull(ws.reader, requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    responseByte := []byte(requestData)

    if len(responseByte) <= 125 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | frame.opcode
        responseFrame[1] = byte(len(responseByte))

        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }
    }

    if len(responseByte) >= 126 && len(responseByte) <= 65535 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | frame.opcode
        responseFrame[1] = 0x7e

        actualPayloadFrameByte := make([]byte, 2)

        binary.BigEndian.PutUint16(actualPayloadFrameByte, uint16(len(responseByte)))
        responseFrame = append(responseFrame, actualPayloadFrameByte...)
        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }

    }

    if len(responseByte) >= 65536 {
        responseFrame := make([]byte, 2)
        responseFrame[0] = 0x80 | frame.opcode
        responseFrame[1] = 0x7f

        actualPayloadFrameByte := make([]byte, 8)

        binary.BigEndian.PutUint64(actualPayloadFrameByte, uint64(len(responseByte)))
        responseFrame = append(responseFrame, actualPayloadFrameByte...)
        responseFrame = append(responseFrame, responseByte...)

        _, err = ws.writer.Write(responseFrame)
        if err != nil {
            return err
        }
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

func (ws *ws) close(frame frame) error {
    if !frame.isMasked {
        ws.conn.Close()
        return errors.New("frame MUST be masked")
    }

    responseFrame := []byte{
        0x88, // FIN + Close opcode
        0x02, // payload length = 2
        0x03, 0xE8, // close code 1000 in network byte order
    }

    _, err := ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    return ws.writer.Flush()
}

func (ws *ws) pong(frame frame) error {
    if !frame.isMasked {
        return ws.close(frame)
    }

    maskingKey := make([]byte, 4)
    _, err := io.ReadFull(ws.reader, maskingKey)
    if err != nil {
        return err
    }

    responseFrame := make([]byte, 2)
    responseFrame[0] = 0x8a
    responseFrame[1] = 0x0
    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    return ws.writer.Flush()
}

type frame struct {
    opcode                 uint8
    payloadIndicator       int64
    isMasked               bool
    actualPayloadLength    int64
    bigEndianPayloadFormat []byte
}

Code Refinement Spotlight

This section presents the refined WebSocket server implementation and highlights each improvement compared to the previous version. Before discussing the refinements, here is the original (unrefined) version of the code:

package main

import (
    "bufio"
    "crypto/sha1"
    "errors"
    "io"
    "log"
    "net"
    "strings"

    b64 "encoding/base64"
)

const (
    secWsKey = "Sec-WebSocket-Key"

    connHeaderKey = "Connection"
    connHeaderVal = "Upgrade"

    upgradeHeaderKey     = "Upgrade"
    upgradeConnHeaderVal = "websocket"
)

func main() {
    port := ":8083"
    listener, err := net.Listen("tcp", port)
    if err != nil {
        log.Fatal(err)
    }

    log.Println("running on ", port)

    for {
        conn, err := listener.Accept()
        if err != nil {
            log.Fatalln(err)
        }

        go handshake(conn)
    }
}

func handshake(conn net.Conn) {
    var secWsAccept string

    reader := bufio.NewReader(conn)

    for {
        header, err := reader.ReadString('\n')
        if err != nil && !errors.Is(err, io.EOF) {
            log.Fatal(err)
        }

        if header == "\r\n" || header == "\n" {
            break
        }

        secWsAcceptVal, err := readHTTPUpgradeHeaderRequest(header)
        if err != nil {
            log.Fatal(err)
        }

        if secWsAcceptVal != "" {
            secWsAccept = secWsAcceptVal
        }
    }

    writer := bufio.NewWriter(conn)

    upgradeResp := []string{
        "HTTP/1.1 101 Web Socket Protocol Handshake",
        "Server: go/echoserver",
        "Upgrade: WebSocket",
        "Connection: Upgrade",
        "Sec-WebSocket-Accept: " + secWsAccept,
        "", // required for extra CRLF
        "", // required for extra CRLF
    }

    _, err := writer.Write([]byte(strings.Join(upgradeResp, "\r\n")))
    if err != nil {
        log.Println(err)
        return
    }

    err = writer.Flush()
    if err != nil {
        log.Println(err)
        return
    }

    ws := ws{
        conn:   conn,
        reader: reader,
        writer: writer,
    }

    ws.handleRequest()
}

// read HTTP upgrade request, returns Sec-WebSocket-Accept header
// value if header is Sec-WebSocket-Accept. Otherwise, checking
// other upgrade header defined at https://datatracker.ietf.org/doc/html/rfc6455#autoid-4
func readHTTPUpgradeHeaderRequest(header string) (string, error) {
    var secWsAccept string

    headerKeys := strings.Split(header, ":")
    headerKey := strings.TrimSpace(headerKeys[0])
    switch {
    case headerKey == upgradeHeaderKey:
        uUpgradeVal := strings.TrimSpace(headerKeys[1])

        if uUpgradeVal != upgradeConnHeaderVal {
            return "", errors.New("upgrade header value is not websocket")
        }

        return "", nil
    case strings.Contains(header, connHeaderKey):
        cConnVal := strings.TrimSpace(headerKeys[1])

        if cConnVal != connHeaderVal {
            return "", errors.New("conenection header value is not upgrade")
        }

        return "", nil
    case strings.Contains(header, secWsKey):
        sSecWsVal := strings.TrimSpace(headerKeys[1])

        secWsAccept = sSecWsVal + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

        sha := sha1.New()
        sha.Write([]byte(secWsAccept))
        encSecWsAccept := sha.Sum(nil)
        secWsAccept = b64.StdEncoding.EncodeToString(encSecWsAccept)

        return secWsAccept, nil
    }

    return "", nil
}

type ws struct {
    conn   net.Conn
    reader *bufio.Reader
    writer *bufio.Writer
}

func (ws *ws) handleRequest() {
    defer ws.conn.Close()

    for {
        frame, err := ws.readRequest(2)
        if err != nil {
            log.Fatal(err)
        }

        switch frame.opcode {
        case 1:
            err := ws.writeTextFrameResponse(frame)
            if err != nil {
                log.Fatal(err)
            }
        case 2:
            log.Println("binary frame")
        case 8:
            log.Println("disconnected from client")
            return
        case 9:
            frame.opcode = 10
        default:
            log.Println("invalid opcode")
        }
    }
}

func (ws *ws) readRequest(requestSize int) (frame, error) {
    data := make([]byte, requestSize)
    _, err := ws.reader.Read(data)
    if err != nil {
        return frame{}, err
    }

    opcode := data[0] & 0xf
    payloadLength := data[1] & 0x7f

    return frame{
        opcode:        opcode,
        payloadLength: int(payloadLength),
    }, nil
}

// writeTextFrameResponse echoes server response as same as
// client request. This works normally when client
// request length is < 126
func (ws *ws) writeTextFrameResponse(frame frame) error {
    // read masking key where masking key located
    // 3rd - 6th byte of request, first 2 already read
    // to retrieve opcode and payload length.
    maskingKey := make([]byte, 4)
    _, err := ws.reader.Read(maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.payloadLength)
    _, err = ws.reader.Read(requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    responseByte := []byte(requestData)

    responseFrame := make([]byte, 2)
    responseFrame[0] = 0x80 | frame.opcode
    responseFrame[1] = byte(len(responseByte))
    responseFrame = append(responseFrame, responseByte...)

    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

type frame struct {
    opcode                 uint8
    payloadLength          int
    actualPayloadLength    int
    bigEndianPayloadFormat []byte
}

Let's review what we changed compared to our previous code as mentioned above:

Aspect	Before Refinement	After Refinement	Why It Matters	Changes On This Article
Request Frame Handling	Loosely handle 1,2,8,9 opcodes	Implements RFC logic for close, ping/pong, and invalid request opcode	No silent feature and failure; Control frame handling	Proper opcode checking at `handleRequest()`
Masking	Server ignores unsmasked client request frame	Server close connection against client immediately	RFC compliant	validate frame masking at `writeTextFrameResponse()`
ping/pong	Server only set frame opcode without send pong response	Server sends pong response frame	Required for heartbeat/liveness	opcode checking at `handleRequest()` and `pong()` definition
Close Frame	Server only log and return when recieves close opcode	Server sends proper close frame (FIN=1, opcode=8, close code=1000)	RFC compliant closing handshke	opcode checking at `handleRequest()` and `close()` definition
Payload-length parsing	Only handles <= 125 when read request frame	Adds proper handling for 126 and 127 (next 2 bytes and 8 bytes)	Prevents truncated reads and incorrect frame interpretation	extended payload length checking at `handleRequest()`
Payload length safety	No limit	Applies `MAX_PAYLOAD_LENGTH`	Prevents DDoS/memory abuse	actual payload length validation at `handleRequest()`
Extended payload length	missing when read request frame	Read and stores next 2 bytes and 8 bytes in big-endian	Essential for frame reconstruction when echo message to client	Read extended payload length at `handleRequest()`
Response frame encoding	Reusing request payload length when building response frame	Computes payload length	Avoids malformed frames	Building response frame at `writeTextFrameResponse()`
`Read`	Uses `Read`	Uses `io.ReadFull`	Prevents partial-frame bugs	Read extended payload length at `handleRequest()` and building response frame at `writeTextFrameResponse()`

Closing Thought on Extended Payload Length

Extended payload handling is one of the most commonly mishandled parts of WebSocket framing, which will lead unexpected behavior or generate silent errors. In this article, this fixes issue where where we ignoring extended payload length which we ignore on previous article. The corrected implementation now parses the 7-bit payload indicator in the second byte WebSocket frame, and checking the next 2 bytes (126) or 8 (127) bytes to get extended payload length information from request frame.

Furthermore, we also discuss more complex concepts like big-endian decoding, safe reads with io.ReadFull, strict mask enforcements, and proper closing connection against intentionalally invalid or malformed request frame.

With this fundamental in place, other WebSocket communication concepts like fragmentation, control-frame handling, and life-cycle management become more easier. And remember that just because it works, it does not mean correct.

Exploring WebSocket Part 1: Building Minimal Echo WebSocket Server From Scratch (RFC 6455 Fundamentals)

Syukur — Wed, 12 Nov 2025 11:55:36 +0000

Introduction

WebSocket protocol enables full-duplex (two-way) communication between client to remote host over a single, long-lived TCP connection. WebSocket protocol is designed to supersede/replace older bidirectional communication technologies that tahat use HTTP as transport layer to benefit from existing infrastructure.

This article explores WebSocket RFC RFC 6455-the official WebSocket specification, starting from create handshake, create client request using Postman, understanding request frame, and echoing/send back user input using WebSocket. Main target audience of this article is a first timer or someone who is unfamiliar with RFC document. We'll create minimal working WebSocket server using Go with several constraints which will be explained as we progress.

Starting WebSocket Handshake

Section 1.3 RFC discusses about creating websocket handshake. Request header for handshake as follows

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: http://example.com
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13

From headers above, header Sec-Websocket-Protocol and Origin are optional
HTTP method use for handshake must GET
Header Sec-WebSocket-Key is use to validate whether client success a handshake attempt. Validation steps begin with take header value without trailing space, then concatenate with 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 resulting dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11. Then resulted string will be encrypted with SHA-1 and encode with base 64.

Upon successful handshake, server respond as follows

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

HTTP response is not 101 or Sec-WebSocket-Accept it MUST equal Sec-WebSocket-Key indicates that handshake attempt is not success between client and server.

handshake function translates handshake steps above.

func handshake(conn net.Conn) {
    var secWsAccept string

    reader := bufio.NewReader(conn)

    for {
        header, err := reader.ReadString('\n')
        if err != nil && !errors.Is(err, io.EOF) {
            log.Fatal(err)
        }

        if header == "\r\n" || header == "\n" {
            break
        }

        secWsAcceptVal, err := readHTTPUpgradeHeaderRequest(header)
        if err != nil {
            log.Fatal(err)
        }

        if secWsAcceptVal != "" {
            secWsAccept = secWsAcceptVal
        }
    }

    writer := bufio.NewWriter(conn)

    upgradeResp := []string{
        "HTTP/1.1 101 Web Socket Protocol Handshake",
        "Server: go/echoserver",
        "Upgrade: WebSocket",
        "Connection: Upgrade",
        "Sec-WebSocket-Accept: " + secWsAccept,
        "", // required for extra CRLF
        "", // required for extra CRLF
    }

    _, err := writer.Write([]byte(strings.Join(upgradeResp, "\r\n")))
    if err != nil {
        log.Println(err)
        return
    }

    err = writer.Flush()
    if err != nil {
        log.Println(err)
        return
    }

    ws := ws{
        conn:   conn,
        reader: reader,
        writer: writer,
    }

    ws.handleRequest()
}

// read HTTP upgrade request, returns Sec-WebSocket-Accept header 
// value if header is Sec-WebSocket-Accept. Otherwise, checking
// other upgrade header defined at https://datatracker.ietf.org/doc/html/rfc6455#autoid-4
func readHTTPUpgradeHeaderRequest(header string) (string, error) {
    var secWsAccept string

    headerKeys := strings.Split(header, ":")
    headerKey := strings.TrimSpace(headerKeys[0])
    switch {
    case headerKey == upgradeHeaderKey:
        uUpgradeVal := strings.TrimSpace(headerKeys[1])

        if uUpgradeVal != upgradeConnHeaderVal {
            return "", errors.New("upgrade header value is not websocket")
        }

        return "", nil
    case strings.Contains(header, connHeaderKey):
        cConnVal := strings.TrimSpace(headerKeys[1])

        if cConnVal != connHeaderVal {
            return "", errors.New("conenection header value is not upgrade")
        }

        return "", nil
    case strings.Contains(header, secWsKey):
        sSecWsVal := strings.TrimSpace(headerKeys[1])

        secWsAccept = sSecWsVal + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

        sha := sha1.New()
        sha.Write([]byte(secWsAccept))
        encSecWsAccept := sha.Sum(nil)
        secWsAccept = b64.StdEncoding.EncodeToString(encSecWsAccept)

        return secWsAccept, nil
    }

    return "", nil
}

Understanding WebSocket Request Format

Section 5.2 of this RFC discusses about data framing. Data transmitted to WebSocket protocol is a sequence of frames as follows.

FIN (1 Bit): Indicates this is a final fragement of the message. First fragment MAY also be the final fragment. Purpose of FIN flag is to support message fragmentation. In short, fragmentation is divide payload data to fragments. We may discuss about fragmentation on another article
RSV1, RSV2, RSV3 (1 Bit each): Reserved fragment. These fragments MUST be 0
opcode (4 Bit): Interprets payload data. If unknown opcode received, endpoint MUST fail websocket connection.
- %x0 denotes continuation frame
- %x1 denotes text frame
- %x2 denotes binary frame
- %x3-%x7 reserved for futher non-control frame
- %x8 denotes connection close
- %x9 denotes ping
- %xA denotes pong
- %xB-F reserved for further control frame
MASK (1 Bit): Defines whether payload data is masked. If set to 1, a masking key presents in masking-key and used to unmask payload data. Masking prevents proxies from misinterpreting WebSocket traffic as HTTP and it is not encription mechanism. All frames sent from client MUST set this bit tot 1.
Payload length is encoded as:
- 7 bits (0-125)
- 7 bit value 126 followed by a 16 bit unsigned integer
- 7 bit value 127 followed by a 64 bit unsigned integer
Masking Key (0 or 4 bytes): All frames sent from client to server are masked by 32 bit value that is contained within the frame. This field is present if the mask bit is set to 1 and is absent if the mask bit set to 0

Control frame is use to communicate state between client and websocket server. Currently, defined opcodes for control frame are 0x8 (close), 0x9 (ping), and 0xA pong. All control frames MUST have payload length of 125 or less, and MUST NOT be fragmented.

Non-control frame are identified by opcodes where most significant bit (leftmost bit from byte sequence) of the opcode is 0. Currently defined non-control frame are 0x1 (text frame) and 0x2 (binary frame). Text frame is a valid UTF-8 format text data. Binary frame is arbitraty binary data whose interpretation is solely up to the application layer

Furthermore, we can divide a frame as several byte/bit parts (begin at 0th index).

1st byte (0th - 7th): FIN + RSVs + opcode
2nd byte (8th - 15th): Mask + Payload length
If payload length < 126: Next 4 bytes are masking key
- Next 4 bytes are masking key
- Following bytes are payload data
If payload length == 126:
- Next 2 bytes is extended payload length
- Next 4 bytes are masking key
- Following bytes are payload data
If payload length == 127:
- Next 8 bytes is extended payload length
- Next 4 bytes are masking key
- Following bytes are payload data

Extended payload length frame exists if length of payload data >= 126. Later in this article, we'll cover only payload length < 125, and we may discuss how to handle payload length >= 126 in another article.

Receiving and Read Client Frame

Send Request To Server

We are going to use Postman to perform request to WebSocket server. Picture below shows how creating a handshake to localhost:8083

Upon successful handshake attempt, Postman will shows like this

Note there is a dropdown above Response tab. It consists of frame types that can be use as request payload. By default, the frame type is text frame.

Recieve Request From Client

After take a look of how data transmitted on WebSocket, we can step into how to recieve and read request. Following codes below demonstrate receiving and read request. (For demonstrative purpose, all code on this article works if payload length is < 126 and assuming request payload is not fragmented)

func (ws *ws) handleRequest() {
    defer ws.conn.Close()

    for {
        // assuming we accept payload length < 126,
        // without fragmentation, and client masks
        // payload
        frame, err := ws.readRequest(2)
        if err != nil {
            log.Fatal(err)
        }

        switch frame.opcode {
        case 1:
            err := ws.writeTextFrameResponse(frame)
            if err != nil {
                log.Fatal(err)
            }
        case 2:
            log.Println("binary frame")
        case 8:
            log.Println("disconnected from client")
            return
        case 9:
            frame.opcode = 10
        default:
            log.Println("invalid opcode")
        }
    }
}

func (ws *ws) readRequest(requestSize int) (frame, error) {
    data := make([]byte, requestSize)
    _, err := ws.reader.Read(data)
    if err != nil {
        return frame{}, err
    }

    opcode := data[0] & 0xf
    payloadLength := data[1] & 0x7f

    return frame{
        opcode:        opcode,
        payloadLength: int(payloadLength),
    }, nil
}

handleRequest() method calls readRequest(2). This means upon receiving request, the server reads first 2 bytes/8 bits requests. When debugging handleRequest() using VSCode, we'll see something like this.

Interpreting First Byte

First byte is data[0] that contains 129 decimal. Convert decimal value to binary, we'll get 10000001 binary value. Recall that first byte of frame contains FIN, RSV, and opcode fields. From left of binary value, FIN occupies first bit (1), RSV1 occupies second bit (0), RSV2 occupies third bit (0), RSV3 occupies fourth bit (0), and opcode occupies fifth to eighth bit (0001).

We retrieve opcode by perform bitwise AND (&) operation between first byte against 0xf/00001111b. Result is follows.

LSB (Least Significant Bit/rightmost bit value) from operation above is 1. This means that server receive text frame request form client.
source

If we don't use & 0x0F, we'll read FIN and RSV bits as part of opcode, which makes opcode invalid.

Interpreting Second Byte

Second byte is data[1] that contains 128 decimal. Convert 128 decimal to binary, we'll get 10000000 binary value. From left to right of decimal, first bit (1) occupied by mask, and second to seventh bit (0000000) occupied by payload length.

Send Response To Client

writeTextFrameResponse() method demonstrate reading request payload and echoing request payload.

// writeTextFrameResponse echoes server response as same as
// client request. This works normally when client
// request payload length is < 126
func (ws *ws) writeTextFrameResponse(frame frame) error {
    // read masking key where masking key located
    // 3rd - 6th byte of request, first 2 already read
    // to retrieve opcode and payload length.
    maskingKey := make([]byte, 4)
    _, err := ws.reader.Read(maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.payloadLength)
    _, err = ws.reader.Read(requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    responseByte := []byte(requestData)

    responseFrame := make([]byte, 2)
    responseFrame[0] = 0x80 | frame.opcode
    responseFrame[1] = byte(len(responseByte))
    responseFrame = append(responseFrame, responseByte...)

    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

Pay attention to section 5.3 on RFC 6455. It states a request from client to server MUST be masked with 32 bit/4 byte random value chosen by client. That means we MUST unmask request payload to retrieve it's original payload.

Formula to retrieve original request payload as follows.

j                   = i MOD 4
transformed-octet-i = original-octet-i XOR masking-key-octet-j

This snippet translates formula above

    // read masking key where masking key located
    // 3rd - 6th byte of request, first 2 already read
    // to retrieve opcode and payload length.
    maskingKey := make([]byte, 4)
    _, err := ws.reader.Read(maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.payloadLength)
    _, err = ws.reader.Read(requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

Take a look on these screenshot on given breakpoint.

When request reaches _, err := ws.reader.Read(mask) where mask is 4 bytes, mask filled with 3rd - 6th byte of request. This due to Read() behavior where it's read sequence of byte by maintaining it's position. Since we've been read 1st - 2nd byte to retrieve FIN, RSV, opcode, and payload length, when we call Read() on this moment we'll read 3rd - 6th byte. The read starting point continues from 2nd byte, not begins from 1st. This approach also applies when read payload message when request reaches _, err = ws.reader.Read(requestData) part of code.

This snippet demonstrates building response frame.

    responseByte := []byte(requestData)

    responseFrame := make([]byte, 2)
    responseFrame[0] = 0x80 | frame.opcode
    responseFrame[1] = byte(len(responseByte))
    responseFrame = append(responseFrame, responseByte...)

    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil

Recall that 1st byte of frame contains FIN, RSV, and opcode, 2nd byte contains payload length. Based on section 5, we MUST NOT mask response data to client, that is why we just append response to defined response frame without masking as client to server does.

Response from server as follows.

Here is full code

package main

import (
    "bufio"
    "crypto/sha1"
    "errors"
    "io"
    "log"
    "net"
    "strings"

    b64 "encoding/base64"
)

const (
    secWsKey = "Sec-WebSocket-Key"

    connHeaderKey = "Connection"
    connHeaderVal = "Upgrade"

    upgradeHeaderKey     = "Upgrade"
    upgradeConnHeaderVal = "websocket"
)

func main() {
    port := ":8083"
    listener, err := net.Listen("tcp", port)
    if err != nil {
        log.Fatal(err)
    }

    log.Println("running on ", port)

    for {
        conn, err := listener.Accept()
        if err != nil {
            log.Fatalln(err)
        }

        go handshake(conn)
    }
}

func handshake(conn net.Conn) {
    var secWsAccept string

    reader := bufio.NewReader(conn)

    for {
        header, err := reader.ReadString('\n')
        if err != nil && !errors.Is(err, io.EOF) {
            log.Fatal(err)
        }

        if header == "\r\n" || header == "\n" {
            break
        }

        secWsAcceptVal, err := readHTTPUpgradeHeaderRequest(header)
        if err != nil {
            log.Fatal(err)
        }

        if secWsAcceptVal != "" {
            secWsAccept = secWsAcceptVal
        }
    }

    writer := bufio.NewWriter(conn)

    upgradeResp := []string{
        "HTTP/1.1 101 Web Socket Protocol Handshake",
        "Server: go/echoserver",
        "Upgrade: WebSocket",
        "Connection: Upgrade",
        "Sec-WebSocket-Accept: " + secWsAccept,
        "", // required for extra CRLF
        "", // required for extra CRLF
    }

    _, err := writer.Write([]byte(strings.Join(upgradeResp, "\r\n")))
    if err != nil {
        log.Println(err)
        return
    }

    err = writer.Flush()
    if err != nil {
        log.Println(err)
        return
    }

    ws := ws{
        conn:   conn,
        reader: reader,
        writer: writer,
    }

    ws.handleRequest()
}


// read HTTP upgrade request, returns Sec-WebSocket-Accept header 
// value if header is Sec-WebSocket-Accept. Otherwise, checking
// other upgrade header defined at https://datatracker.ietf.org/doc/html/rfc6455#autoid-4
func readHTTPUpgradeHeaderRequest(header string) (string, error) {
    var secWsAccept string

    headerKeys := strings.Split(header, ":")
    headerKey := strings.TrimSpace(headerKeys[0])
    switch {
    case headerKey == upgradeHeaderKey:
        uUpgradeVal := strings.TrimSpace(headerKeys[1])

        if uUpgradeVal != upgradeConnHeaderVal {
            return "", errors.New("upgrade header value is not websocket")
        }

        return "", nil
    case strings.Contains(header, connHeaderKey):
        cConnVal := strings.TrimSpace(headerKeys[1])

        if cConnVal != connHeaderVal {
            return "", errors.New("conenection header value is not upgrade")
        }

        return "", nil
    case strings.Contains(header, secWsKey):
        sSecWsVal := strings.TrimSpace(headerKeys[1])

        secWsAccept = sSecWsVal + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

        sha := sha1.New()
        sha.Write([]byte(secWsAccept))
        encSecWsAccept := sha.Sum(nil)
        secWsAccept = b64.StdEncoding.EncodeToString(encSecWsAccept)

        return secWsAccept, nil
    }

    return "", nil
}

type ws struct {
    conn   net.Conn
    reader *bufio.Reader
    writer *bufio.Writer
}

func (ws *ws) handleRequest() {
    defer ws.conn.Close()

    for {
        frame, err := ws.readRequest(2)
        if err != nil {
            log.Fatal(err)
        }

        switch frame.opcode {
        case 1:
            err := ws.writeTextFrameResponse(frame)
            if err != nil {
                log.Fatal(err)
            }
        case 2:
            log.Println("binary frame")
        case 8:
            log.Println("disconnected from client")
            return
        case 9:
            frame.opcode = 10
        default:
            log.Println("invalid opcode")
        }
    }
}

func (ws *ws) readRequest(requestSize int) (frame, error) {
    data := make([]byte, requestSize)
    _, err := ws.reader.Read(data)
    if err != nil {
        return frame{}, err
    }

    opcode := data[0] & 0xf
    payloadLength := data[1] & 0x7f

    return frame{
        opcode:        opcode,
        payloadLength: int(payloadLength),
    }, nil
}

// writeTextFrameResponse echoes server response as same as
// client request. This works normally when client
// request length is < 126
func (ws *ws) writeTextFrameResponse(frame frame) error {
    // read masking key where masking key located
    // 3rd - 6th byte of request, first 2 already read
    // to retrieve opcode and payload length.
    maskingKey := make([]byte, 4)
    _, err := ws.reader.Read(maskingKey)
    if err != nil {
        return err
    }

    requestData := make([]byte, frame.payloadLength)
    _, err = ws.reader.Read(requestData)
    if err != nil {
        return err
    }

    // unmasking request payload, refer to https://datatracker.ietf.org/doc/html/rfc6455#autoid-24
    for i := 0; i < len(requestData); i++ {
        requestData[i] = requestData[i] ^ maskingKey[i%4]
    }

    responseByte := []byte(requestData)

    responseFrame := make([]byte, 2)
    responseFrame[0] = 0x80 | frame.opcode
    responseFrame[1] = byte(len(responseByte))
    responseFrame = append(responseFrame, responseByte...)

    _, err = ws.writer.Write(responseFrame)
    if err != nil {
        return err
    }

    err = ws.writer.Flush()
    if err != nil {
        return err
    }

    return nil
}

type frame struct {
    opcode        uint8
    payloadLength int
}

References

Saving Budget With OpenTelemetry Sampling

Syukur — Thu, 23 Oct 2025 01:57:10 +0000

Background

On early October 2025, we was doing PoC of using OpenTelemetry
exporter for Google Cloud Trace for internal API. The API has been
generated 42 millions spans since October 1st - October 6th.
Most of spans return unset status, and we are happy with it.
Cloud Trace service is not free. It charges after million spans generated by your application. Since we are not interested with every span generated and captured by Cloud Trace, we was conducting research on OpenTelemetry trace sampling. The purpose is crystal clear - to ingest trace/spans that we are interested into, and to save budget

In this article, we are going to explore definition of sampling, sampling method for OpenTelemetry trace, how they behave, their implementation, strengths and drawbacks, and their challenges.

Sampling Definition

Oxford dictionary defines sampling as a small amount of a substance taken from a larger amount and tested in order to obtain information about the substance. In observability realm, we can say sampling is a way to gather a group of telemetry data (it could be trace, span, or metrics) where they are represent the whole telemetry data. The main purpose of sampling is to reduce costs without losing visibility.

When To and Not To Sample

OpenTelemetry mentioned there are situations that you might need sampling

Application generates more than 1000 traces per second
Most of trace data represents healthy traffic with little variation
You are interested in some criteria like errors or high latency
You have domain-specific criteria you can use to determine relevant data beyon errors and latency
You have common rules to collect or drop data
You have a way to tell your application to sample data based on their volume
You have ability to store unsampled data
Your biggest concern is your budget

In addition, OpenTelemetry tells there are situation that you
might not need sampling

Your application generates small data (tens of small traces per second or lower)
You only use observability data in aggregate, and can thus pre-aggregate data
You are bound to regulation where you are not allow to drop data

There are head sampling and tail sampling to perform
OpenTelemetry sampling

Head Sampling

Head sampling is a sampling technique used to make a sampling
decision as early as possible. This decision to sample or drop
a trace or span, not inspect trace end-to-end

There are strengths of this sampling technique:

Easy to implement and understand
Efficient
Can be done at any point in trace collection pipeline

However, the primary downside/side effect of this sampling
is it is not possible to sample whole trace. For example,
you are unable to make sure that you only collect trace
with error status in head sampling. For situation or
criteria like this, you might need tail sampling.

We are going to use these configuration files throughout
demonstration of head sampling.

Dockerfile

A Dockerfile to transform application to Docker Image. We'll use it later alongside Docker Compose

FROM golang:1.22-alpine AS build
ARG APP_VERSION=latest

WORKDIR /src/

COPY . /src/.

RUN CGO_ENABLED=0 go build -o /bin/go-tracing-head-sampling ./tracing-head-sampling/main.go

# final - service
FROM alpine as api-service

COPY --from=build /bin/go-tracing-head-sampling /bin/go-tracing-head-sampling

# HTTP Port
EXPOSE 9320

ENTRYPOINT ["/bin/go-tracing-head-sampling"]

docker-compose.yaml

Docker Compose file to run application and their dependencies. We are going to use OpenTelemetry Collector to ingest traces and spans generated by application, Grafana Tempo to store traces and spans, and Grafana Dashboard to visualize result. We also need a load generator to automatically generate traces with HTTP calls.

version: "3"

networks:
  observability:

services:
  tempo:
    image: grafana/tempo:main-c5323bf
    command: [ "-config.file=/etc/tempo.yaml" ]
    volumes:
      - ./config/tempo-config.yaml:/etc/tempo.yaml
      - ./config/tempo-data:/var/tempo
    ports:
      - "3200:3200" # tempo
      - "4317"
      - "4318"
    networks:
      - observability

  otel-collector:
    image: otel/opentelemetry-collector:latest
    volumes:
      - ./config/otel-config.yaml:/etc/otel/config.yaml
    command:
      - '--config=/etc/otel/config.yaml'
    ports:
      - "4317:4317" #grpc
      - "4318:4318" #http
    networks:
      - observability

  app:
    container_name: app
    build:
      context: ./
      dockerfile: ./Dockerfile
    ports:
      - 9320:9320
    networks:
      - observability
    depends_on:
      - otel-collector
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
      - OTEL_SERVICE_NAME=go-loki-app-demo

  grafana:
    environment:
      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    entrypoint:
      - sh
      - -euc
      - |
        mkdir -p /etc/grafana/provisioning/datasources
        cat <<EOF > /etc/grafana/provisioning/datasources/ds.yaml
        apiVersion: 1
        datasources:
        - name: Loki
          type: loki
          access: proxy 
          orgId: 1
          url: http://loki:3100
          basicAuth: false
          isDefault: true
          version: 1
          editable: false
        - name: Tempo
          type: tempo
          access: proxy 
          orgId: 1
          url: http://tempo:3200
          basicAuth: false
          version: 1
          editable: false
        EOF
        /run.sh
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    networks:
      - observability

  load-generator:
    image: alpine/curl:latest
    volumes:
      - ./config/load-generator.sh:/usr/local/bin/load-generator.sh
    command: ["sh", "/usr/local/bin/load-generator.sh"]
    networks:
      - observability
    depends_on:
      - app

load-generator.sh

A script to send HTTP request to application. We will send 10 HTTP requests to server.


curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

otel-config.yaml

A configuration file for OpenTelemetry Collector

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlphttp/trace:
    endpoint: http://tempo:4318
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/trace]

main.go NewTracer function is the way we done head sampling in Go. It only collects 10% of generated traces.

// tracerName will be initialized after NewTracer() has been called
var tracerName string

// customTracer will be initialized after NewTracer() has been called
var customTracer = otel.Tracer(tracerName)


func NewTracer(
    ctx context.Context,
    serviceName string,
) error {
    propagator := propagation.NewCompositeTextMapPropagator(
        propagation.TraceContext{},
        propagation.Baggage{},
    )
    otel.SetTextMapPropagator(propagator)

    traceClientHTTP := otlptracehttp.NewClient(
        otlptracehttp.WithInsecure(),
        otlptracehttp.WithEndpoint("otel-collector:4318"),
    )

    traceExporter, err := otlptrace.New(
        ctx,
        traceClientHTTP,
    )
    if err != nil {
        return err
    }

    res, err := resource.New(
        ctx,
        resource.WithContainer(),
        resource.WithFromEnv(),
    )
    if err != nil {
        return err
    }

    tracerProvider := traceSdk.NewTracerProvider(
        traceSdk.WithBatcher(
            traceExporter,
            traceSdk.WithBatchTimeout(time.Second),
        ),
        traceSdk.WithResource(
            res,
        ),
        traceSdk.WithSampler(traceSdk.TraceIDRatioBased(0.1)),
    )

    tracerName = serviceName

    otel.SetTracerProvider(tracerProvider)

    return nil
}

Here is driver code and trace implementation

func main() {
    ctx := context.Background()

    log.Println(os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT"))

    err := NewTracer(ctx, "go-observability")
    if err != nil {
        log.Fatalln("fail setup tracer")
    }

    RunServer()
}

func RunServer() {
    http.HandleFunc("/", home())
    if err := http.ListenAndServe(":9320", nil); err != nil {
        log.Fatalf("could not start server: %v\n", err)
    }
}

func home() http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        respCode := 200

        ctx := r.Context()

        ctx, span := HTTPLevelSpan(ctx, r)
        defer span.End()

        failQuery := r.URL.Query().Get("fail")

        if failQuery != "" {
            respCode = 500

            isFail, err := strconv.ParseBool(failQuery)
            if err != nil {
                w.WriteHeader(http.StatusInternalServerError)
                w.Write([]byte("error parse query"))

                log.Println("error parse query")

                return
            }

            if isFail {
                w.WriteHeader(http.StatusInternalServerError)
                w.Write([]byte("encounter fail"))

                log.Println("encounter fail")

                return
            }
        }

        w.WriteHeader(respCode)
        w.Write([]byte("Hello, World!"))
    }
}

func HTTPLevelSpan(
    ctx context.Context,
    r *http.Request,
) (context.Context, trace.Span) {
    spanName := fmt.Sprintf("%s %s", r.Method, r.URL.String())

    ctx, span := customTracer.Start(ctx, spanName)

    if span.IsRecording() {
        // this golang version of this repo is not compatible to
        // use go.opentelemetry.io/otel/semconv/v1.32.0, for purpose of
        // this example, we are using manually type semconv
        span.SetAttributes(attribute.String("http.request.method", r.Method))
        span.SetAttributes(attribute.String("server.address", r.RemoteAddr))
        span.SetAttributes(attribute.String("url.full", r.URL.String()))
    }

    return ctx, span
}

Run the whole application with docker compose up -d. Explore Grafana
dashboard with Grafana Tempo data source. It might be look like this.

Normally, when we don't apply head sampling, we will get 10 traces
instead of 1. Since we are using head sampling with 10% generated
trace to be sampled, we only get 1 instead of 10.

Tail Sampling

Tail sampling is a way to sample a trace by considering all
or part of span within a trace. Tail sampling enables you
to choose what to sample and what to drop, based on your
interest. You can only sample traces with error status,
trace with certain duration, or trace with specific
attribute. For more tail sampling configuration, you
can find it here

Aside from it's strength, there are downsides of implementing
tail sampling

Difficult to implement
Diffuclt to operate
Today, it is vendor-specific technology

We are going to use these configuration files throughout
demonstration of tail sampling.

Dockerfile

FROM golang:1.22-alpine AS build
ARG APP_VERSION=latest

WORKDIR /src/

COPY . /src/.

RUN CGO_ENABLED=0 go build -o /bin/go-tracing-tail-sampling ./tracing-tail-sampling/main.go

# final - service
FROM alpine as api-service

COPY --from=build /bin/go-tracing-tail-sampling /bin/go-tracing-tail-sampling

# HTTP Port
EXPOSE 9320

ENTRYPOINT ["/bin/go-tracing-tail-sampling"]

docker-compose.yaml

version: "3"

networks:
  observability:

services:
  tempo:
    image: grafana/tempo:main-c5323bf
    command: [ "-config.file=/etc/tempo.yaml" ]
    volumes:
      - ./config/tempo-config.yaml:/etc/tempo.yaml
      - ./config/tempo-data:/var/tempo
    ports:
      - "3200:3200" # tempo
      - "4317"
      - "4318"
    networks:
      - observability

  otel-collector:
    image: otel/opentelemetry-collector:latest
    volumes:
      - ./config/otel-config.yaml:/etc/otel/config.yaml
    command:
      - '--config=/etc/otel/config.yaml'
    ports:
      - "4317:4317" #grpc
      - "4318:4318" #http
    networks:
      - observability

  app:
    container_name: app
    build:
      context: ./
      dockerfile: ./Dockerfile
    ports:
      - 9320:9320
    networks:
      - observability
    depends_on:
      - otel-collector
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
      - OTEL_SERVICE_NAME=go-loki-app-demo

  grafana:
    environment:
      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    entrypoint:
      - sh
      - -euc
      - |
        mkdir -p /etc/grafana/provisioning/datasources
        cat <<EOF > /etc/grafana/provisioning/datasources/ds.yaml
        apiVersion: 1
        datasources:
        - name: Loki
          type: loki
          access: proxy 
          orgId: 1
          url: http://loki:3100
          basicAuth: false
          isDefault: true
          version: 1
          editable: false
        - name: Tempo
          type: tempo
          access: proxy 
          orgId: 1
          url: http://tempo:3200
          basicAuth: false
          version: 1
          editable: false
        EOF
        /run.sh
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    networks:
      - observability

  load-generator:
    image: alpine/curl:latest
    volumes:
      - ./config/load-generator.sh:/usr/local/bin/load-generator.sh
    command: ["sh", "/usr/local/bin/load-generator.sh"]
    networks:
      - observability
    depends_on:
      - app

load-generator.sh We will send 5 HTTP requests to demonstrate how tail sampling works.

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

curl -v http://host.docker.internal:9320/?fail=true 
sleep 0.2

curl -v http://host.docker.internal:9320/ 
sleep 0.2

otel-config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  tail_sampling:
    decision_wait: 10s # Optional: Time to wait before making a sampling decision
    num_traces: 10000 # Optional: Number of traces to keep in memory
    expected_new_traces_per_sec: 100 # Optional: Expected new traces per second for resource allocation
    policies:
      - name: errors-only-policy
        type: status_code
        status_code:
          status_codes: [ERROR]

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/trace]

Rest of configuration file are same, but the biggest changes
lies on OpenTelemetry configuration file and Docker Compose
file.

In OpenTelemetry config file, we define more specific processor
rules instead of having batch rule. At this moment, we are
interested with only traces that return error status.
Consequently, no matter how important or numerous spans within
a trace as long as they don't return error status, they will
be dropped.

We are going to use contrib OpenTelemetry Docker image for
OpenTelemetry collector, because core image is not supported
for tail sampling processor (read more about it here)

When accessing Grafana explore with Grafana Tempo data source,
we'll get something like this

Among all requests, our OpenTelemetry collector will only sample
trace with error status. In this example, we simulate the error
by checking fail query on HTTP URL.

Conducted Researches

There are several researches regarding OpenTelemetry sampling

Tail sampling had highest CPU, memory, and network overhead compared to head sampling. This is a trade off for capturing errors.
Enabling tail sampling consumes more physical resources compared to disable tail sampling. Consider head sampling for representative trace/span

References

https://opentelemetry.io/docs/concepts/sampling/
https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/34418
https://opentelemetry.io/docs/concepts/sampling/
https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor
Karkan, T. M. (2024). Performance Overhead Of OpenTelemetry Sampling Methods In A Cloud Infrastructure (Dissertation). Retrieved from https://urn.kb.se/resolve?urn=urn:nbn:se:umu:diva-225869
Shuvo, G. K. (2021). Tail Based Sampling Framework for Distributed Tracing Using Stream Processing (Dissertation). Retrieved from https://urn.kb.se/resolve?urn=urn:nbn:se:kth:diva-306699

Application Tracing With Golang, OpenTelemetry, and Grafana Tempo

Syukur — Thu, 28 Aug 2025 09:34:50 +0000

Trace

Trace is a record or history from a request. Trace give us big picture abour what is happening from application accepts request to return a response. This record is build above span.

Span

Span is a unit that records particular operation within certain time window. Span contains information about trace name, timestamp from request starts to when it ends, and other informations in form of span attributes such as HTTP request, HTTP URL, and URL path. This is an example of hello span on json format.

{
  "name": "hello",
  "context": {
    "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "051581bf3cb55c13"
  },
  "parent_id": null,
  "start_time": "2022-04-29T18:52:58.114201Z",
  "end_time": "2022-04-29T18:52:58.114687Z",
  "attributes": {
    "http.route": "some_route1"
  },
  "events": [
    {
      "name": "Guten Tag!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

Span above contains informations about

a name hello
span lifetime on start_time and end_time fields
http.route span attribute records information URL
event field that tells us what happens during span lifetime

Span hello is a parent span, because value on parent_id field is null. Pay attention on hello_greetings span below.

{
  "name": "hello-greetings",
  "context": {
    "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "5fb397be34d26b51"
  },
  "parent_id": "051581bf3cb55c13",
  "start_time": "2022-04-29T18:52:58.114304Z",
  "end_time": "2022-04-29T22:52:58.114561Z",
  "attributes": {
    "http.route": "some_route2"
  },
  "events": [
    {
      "name": "hey there!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    },
    {
      "name": "bye now!",
      "timestamp": "2022-04-29T18:52:58.114585Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

Value of parent_id field on greetings span is same as value of span_id on hello span. We call greetings span is a child span from hello span. Below is hello-salutation span, where it's parent_id is equal to hello's span_id.

{
  "name": "hello-salutations",
  "context": {
    "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "93564f51e1abe1c2"
  },
  "parent_id": "051581bf3cb55c13",
  "start_time": "2022-04-29T18:52:58.114492Z",
  "end_time": "2022-04-29T18:52:58.114631Z",
  "attributes": {
    "http.route": "some_route3"
  },
  "events": [
    {
      "name": "hey there!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

OpenTelemetry Collector

Collector is a component to receive, extract, and export telemetry data. OpenTelemetry collector is use to receive, extract, and export telemetry data in various formats such as Jaeger, Prometheus, or FluentBit. OpenTelemetry collector built above several components:

Receiver

Receiver focus on collecting data from various sources and formats. Here is an example of receiver.

receivers:
  # Data sources: logs
  fluentforward:
    endpoint: 0.0.0.0:8006

  # Data sources: metrics
  hostmetrics:
    scrapers:
      cpu:
      disk:
      filesystem:
      load:
      memory:
      network:
      process:
      processes:
      paging:

  # Data sources: traces
  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      thrift_binary:
      thrift_compact:
      thrift_http:

  # Data sources: traces, metrics, logs
  kafka:
    protocol_version: 2.0.0

  # Data sources: traces, metrics
  opencensus:

  # Data sources: traces, metrics, logs
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: cert.pem
          key_file: cert-key.pem
      http:
        endpoint: 0.0.0.0:4318

  # Data sources: metrics
  prometheus:
    config:
      scrape_configs:
        - job_name: otel-collector
          scrape_interval: 5s
          static_configs:
            - targets: [localhost:8888]

  # Data sources: traces
  zipkin:

Processor

Processor is use to process data from receiver. Processed data on this component cosists of filtering, renaming, or recalculating. We could not only define processor once, but also multiple of them, depending on our needs. Outcome of telemetry data depends on sequence or order of data processing on this component. Here is example of processor definition

processors:
  # Data sources: traces
  attributes:
    actions:
      - key: environment
        value: production
        action: insert
      - key: db.statement
        action: delete
      - key: email
        action: hash

  # Data sources: traces, metrics, logs
  batch:

  # Data sources: metrics, metrics, logs
  filter:
    error_mode: ignore
    traces:
      span:
        - 'attributes["container.name"] == "app_container_1"'
        - 'resource.attributes["host.name"] == "localhost"'
        - 'name == "app_3"'
      spanevent:
        - 'attributes["grpc"] == true'
        - 'IsMatch(name, ".*grpc.*")'
    metrics:
      metric:
        - 'name == "my.metric" and resource.attributes["my_label"] == "abc123"'
        - 'type == METRIC_DATA_TYPE_HISTOGRAM'
      datapoint:
        - 'metric.type == METRIC_DATA_TYPE_SUMMARY'
        - 'resource.attributes["service.name"] == "my_service_name"'
    logs:
      log_record:
        - 'IsMatch(body, ".*password.*")'
        - 'severity_number < SEVERITY_NUMBER_WARN'

  # Data sources: traces, metrics, logs
  memory_limiter:
    check_interval: 5s
    limit_mib: 4000
    spike_limit_mib: 500

  # Data sources: traces
  resource:
    attributes:
      - key: cloud.zone
        value: zone-1
        action: upsert
      - key: k8s.cluster.name
        from_attribute: k8s-cluster
        action: insert
      - key: redundant-attribute
        action: delete

  # Data sources: traces
  probabilistic_sampler:
    hash_seed: 22
    sampling_percentage: 15

  # Data sources: traces
  span:
    name:
      to_attributes:
        rules:
          - ^\/api\/v1\/document\/(?P<documentId>.*)\/update$
      from_attributes: [db.svc, operation]
      separator: '::'

Exporter

Exporter is component that aims to export telemetry data that has been processed to other backend processes such as Jaeger, Zipkin, Prometheus, or Kafka. Each key on exporter use type/name format, where type defines kind of exporter like Jaeger, Kafka, or OpenTelemetry, and name is an optional field to seperate exporter that has same type. Here is an example of exporter.

exporters:
  # Data sources: traces, metrics, logs
  file:
    path: ./filename.json

  # Data sources: traces
  otlp/jaeger:
    endpoint: jaeger-server:4317
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem

  # Data sources: traces, metrics, logs
  kafka:
    protocol_version: 2.0.0

  # Data sources: traces, metrics, logs
  # NOTE: Prior to v0.86.0 use `logging` instead of `debug`
  debug:
    verbosity: detailed

  # Data sources: traces, metrics
  opencensus:
    endpoint: otelcol2:55678

  # Data sources: traces, metrics, logs
  otlp:
    endpoint: otelcol2:4317
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem

  # Data sources: traces, metrics
  otlphttp:
    endpoint: https://otlp.example.com:4318

  # Data sources: metrics
  prometheus:
    endpoint: 0.0.0.0:8889
    namespace: default

  # Data sources: metrics
  prometheusremotewrite:
    endpoint: http://prometheus.example.com:9411/api/prom/push
    # When using the official Prometheus (running via Docker)
    # endpoint: 'http://prometheus:9090/api/v1/write', add:
    # tls:
    #   insecure: true

  # Data sources: traces
  zipkin:
    endpoint: http://zipkin.example.com:9411/api/v2/spans

Instrumenting Go Application With OpenTelemetry Tracing

Spin Up Collector

Trace and span data emitted by server will be collected, stored, filtered, and exported by OpenTelemetry collector. The rules of collector defined by a configuration file as shown below.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlphttp/trace:
    endpoint: http://tempo:4318
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/trace]

OpenTelemetry collector will collects all emmited traces and spans as mentioned at receivers.otlp.http.endpoint field. Value of this field is 0.0.0.0:4318 where 0.0.0.0 means the collector will listen to all IPv4 addresses.

After traces and spans has been collected by receiver, then they will be processed on processor. In this example, the data will be processed as batch.

Processed data then will be exported to trace visualization technology such as Grafana Tempo. Exporters are defined on exporters section.

Finally, we compile collecting, processing, and exporting traces data on service field.

Defining Exporter

Exporter on code level aims to connect application with collector. NewTracer function below explains exporter creation and connects created exporter with collector.

package trace

import (
    "context"
    "fmt"
    "net/http"
    "runtime"
    "time"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/trace"

    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/resource"
    traceSdk "go.opentelemetry.io/otel/sdk/trace"
)

var globalServiceName string

func NewTracer(
    ctx context.Context,
    serviceName string,
) error {
    propagator := propagation.NewCompositeTextMapPropagator(
        propagation.TraceContext{},
        propagation.Baggage{},
    )
    otel.SetTextMapPropagator(propagator)

  // Create OpenTelemetry tracing client that exports
  // trace data to OpenTelemetry HTTP receiver
    traceClientHTTP := otlptracehttp.NewClient(
        otlptracehttp.WithInsecure(),
    )

    traceExporter, err := otlptrace.New(
        ctx,
        traceClientHTTP,
    )
    if err != nil {
        return err
    }

    res, err := resource.New(
        ctx,
        resource.WithContainer(),
        resource.WithFromEnv(),
    )
    if err != nil {
        return err
    }

    tracerProvider := traceSdk.NewTracerProvider(
        traceSdk.WithBatcher(
            traceExporter,
            traceSdk.WithBatchTimeout(time.Second),
        ),
        traceSdk.WithResource(
            res,
        ),
    )

    globalServiceName = serviceName

    otel.SetTracerProvider(tracerProvider)

    return nil
}

Define Tracing Components

In this article, we are going to record events on HTTP request and business logic/service by creating trace and generate span from each component. HTTPLevelSpan to trace over HTTP handler, while ServiceLevelSpan to trace over service level.

package trace

import (
    "context"
    "fmt"
    "net/http"
    "runtime"
    "time"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/trace"

    "go.opentelemetry.io/otel/attribute"
)

func HTTPLevelSpan(
    ctx context.Context,
    r *http.Request,
) (context.Context, trace.Span) {
    spanName := fmt.Sprintf("%s %s", r.Method, r.URL.String())
    ctx, span := otel.Tracer(globalServiceName).Start(ctx, spanName)

    if span.IsRecording() {
        span.SetAttributes(attribute.String("http.request.method", r.Method))
        span.SetAttributes(attribute.String("server.address", r.RemoteAddr))
        span.SetAttributes(attribute.String("url.full", r.URL.String()))
    }

    return ctx, span
}

func ServiceLevelSpan(
    ctx context.Context,
) (context.Context, trace.Span) {
    pc := make([]uintptr, 10)
    runtime.Callers(2, pc)
    f := runtime.FuncForPC(pc[0])

    ctx, span := otel.Tracer(globalServiceName).Start(ctx, f.Name())

    if span.IsRecording() {
        span.SetAttributes(attribute.String("code.function.name", f.Name()))
    }

    return ctx, span
}

When conducting trace on any aspect of application like HTTP, service, GRPC, or database, it is recommended to follow Semantic Convention or semconv. Semantic convention give us meaningful information about generated trace and span. Based on code above, code.function, server.address, and url.full are examples of semantic convention.

Instrumenting Application

Code below demonstrate usages of HTTPLevelSpan and ServiceLevelSpan

package server

import (
    "log"
    "net/http"
)

func RunServer() {
    http.HandleFunc("/", home())
    if err := http.ListenAndServe(":9320", nil); err != nil {
        log.Fatalf("could not start server: %v\n", err)
    }
}

package server

import (
    "fmt"
    "log"
    "net/http"
    "strconv"
    "time"

    "go-trace-demo/service"
    "go-trace-demo/utils/metrics"
    utilsTrace "go-trace-demo/utils/trace"
)

func home() http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

    ctx, span := utilsTrace.HTTPLevelSpan(ctx, r)
        defer span.End()

        respCode := 200

        failQuery := r.URL.Query().Get("fail")

        if failQuery != "" {
            respCode = 500

            isFail, err := strconv.ParseBool(failQuery)
            if err != nil {
                w.WriteHeader(http.StatusInternalServerError)
                w.Write([]byte("error parse query"))

                return
            }

            if isFail {
                w.WriteHeader(http.StatusInternalServerError)
                w.Write([]byte("encounter fail"))

                return
            }
        }

        err := service.GetUserByID(ctx)
        if err != nil {
            return
        }

        err = service.ListStores(ctx)
        if err != nil {
            return
        }

        w.Write([]byte("Hello, World!"))
    }
}

package service

import (
    "context"

    utilsTrace "go-trace-demo/utils/trace"
)

func GetUserByID(
    ctx context.Context,
) error {
    ctx, span := utilsTrace.ServiceLevelSpan(ctx)

    defer span.End()

    return nil
}

func ListStores(
    ctx context.Context,
) error {
    ctx, span := utilsTrace.ServiceLevelSpan(ctx)

    defer span.End()

    return nil
}

Below is main code

func main() {
    ctx := context.Background()

    serviceName := os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT")

    err := utilsTrace.NewTracer(ctx, serviceName)
    if err != nil {
        log.Fatalln("fail setup tracer")
    }

    server.RunServer()
}

Glue Everything

We'll run application, OpenTelemetry Collector, and Grafana Tempo using docker compose file below

version: "3"

networks:
  observability:

services:
  tempo:
    image: grafana/tempo:main-c5323bf
    command: [ "-config.file=/etc/tempo.yaml" ]
    volumes:
      - ./config/tempo-config.yaml:/etc/tempo.yaml
      - ./config/tempo-data:/var/tempo
    ports:
      - "3200:3200" # tempo
      - "4317" # open this port for OpenTelemetry gRPC exporter
      - "4318" # open this port for OpenTelemetry HTTP exporter
    networks:
      - observability

  otel-collector:
    image: otel/opentelemetry-collector:latest
    volumes:
      - ./config/otel-config.yaml:/etc/otel/config.yaml
    command:
      - '--config=/etc/otel/config.yaml'
    ports:
      - "4317:4317" #grpc
      - "4318:4318" #http
    depends_on:
      - loki
    networks:
      - observability

  app:
    container_name: app
    build:
      context: ./
      dockerfile: ./Dockerfile
    ports:
      - 9320:9320
    networks:
      - observability
    depends_on:
      - otel-collector
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
      - OTEL_SERVICE_NAME=go-loki-app-demo

  grafana:
    environment:
      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    entrypoint:
      - sh
      - -euc
      - |
        mkdir -p /etc/grafana/provisioning/datasources
        cat <<EOF > /etc/grafana/provisioning/datasources/ds.yaml
        apiVersion: 1
        datasources:
        - name: Loki
          type: loki
          access: proxy 
          orgId: 1
          url: http://loki:3100
          basicAuth: false
          isDefault: true
          version: 1
          editable: false
        - name: Tempo
          type: tempo
          access: proxy 
          orgId: 1
          url: http://tempo:3200
          basicAuth: false
          version: 1
          editable: false
        EOF
        /run.sh
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    networks:
      - observability

Our application defined at service.app section. Be aware that we define OTEL_EXPORTER_OTLP_ENDPOINT environment variables for application. The reason is when we are defining OpenTelemetry HTTP exporter, we don't specify OpenTelemetry collector address. OpenTelemetry will look for OTEL_EXPORTER_OTLP_ENDPOINT environment variable to know where application should send trace data. If you have specific OpenTelemetry exporter, you can use WithEndpointURL argument for otlptracehttp.NewClient. Additionally, we define OTEL_SERVICE_NAME environment variable where the purpose is for OpenTelemetry identify what service they are receive the trace data. If OTEL_SERVICE_NAME not provided, OpenTelemetry will fill with unknown_service value.

Visualizing Traces Using Grafana Tempo

After successful container creation with Docker compose, let's generate trace data by accessing localhost:9320/. Next, access Grafana on localhost:3000, then head to Exlpore menu by click dropdown menu on top left corner.

Switch to Search query type instead of TraceQL, then click Service Name dropdown. It will show service name we provided on OTEL_SERVICE_NAME
. By click Run Query, we'll have something like this.

Explore trace data by click available row on Trace column. We will be redirected to trace detail like this
.

Additionally, explore span attribute by click one of span. We will see span attribute and resource attribute we defined when we are creating OpenTelemetry trace instance.

References

Instrumentasi Aplikasi Golang Menggunakan Prometheus

Syukur — Wed, 05 Feb 2025 09:29:49 +0000

Foto oleh Daniel Korpai on Unsplash

Mengapa Perlu Monitoring Aplikasi?

Tom Wilkie memperkenalkan metodologi USE (Utilization, Saturation, Error)untuk mengukur penggunaan perangkat keras seperti kecepatan pembacaan oleh disk (I/O), penggunaan memori, dan jaringan. Namun metodologi tersebut tidak menunjukkan performa aplikasi dan bagaimana pengguna berinteraksi dengan aplikasi. Oleh karena itu, ia mengenalkan metodologi RED (Rate, Error, Duration). Dengan menggunakan metodologi RED, pengembang bisa mengetahui bahwa durasi yang tinggi menandakan aplikasi berjalan lemot atau menjawab pertanyaan kapan request terbanyak terjadi dalam rentang waktu tertentu.

Tentang Prometheus

Prometheus adalah perangkat lunak yang dikembangkan oleh SoundCloud. Prometheus digunakan untuk memantau (monitoring) kinerja aplikasi dan memberi peringatan (alerting) jika terjadi kendala pada aplikasi. Prometheus mengumpulkan dan menyimpan data metrik (metrics) dalam format deret waktu (time series). Metrik disimpan menggunakan penanda waktu (timestamp) beserta label berupa pasangan kunci dan nilai (key-value pairs). Prometheus mengumpulkan data metrik dari aplikasi secara terus menerus atau biasa dikenal sebagai pull mechanism.

Berikut ini adalah arsitektur Prometheus.

Prometheus mengambil data metrik dengan cara melakukan pull atau scrape dari Prometheus target, di mana target ini bisa berupa aplikasi HTTP atau database. Prometheus mengetahui target aplikasi yang akan di-scrape melalui service discovery yang bisa dilakukan secara otomatis oleh Kubernetes atau kita mendefinisikan sendiri targetnya menggunakan configuration file. Metrik yang berhasil scrape oleh Prometheus bisa kita oleh menggunakan PromQL.

Metrik Prometheus

Prometheus memiliki 4 buah metrik yang digunakan secara spesifik untuk mengukur kinerja aplikasi

Counter
Counter merupakan metrik dengan sifat monoton naik, tidak bisa berkurang, namun nilainya bisa berubah menjadi 0. Counter bisa digunakan untuk memantau berapa request yang berhasil diproses dan jumlah galat (error).
Gauge
Gauge merupakan metrik yang hanya bisa naik atau turun. Gauge bisa digunakan untuk memantau konsumsi memori, konsumsi CPU, serta jumlah request yang terjadi secara konkuren.
Histogram
Histogram merupakan metrik yang mengumpulkan beberapa nilai hasil observasi dalam rentang tertentu yang bisa dikonfigurasi. Histogram bisa digunakan untuk memantau waktu yang dibutuhkan untuk menyelesaikan sebuah request dalam rentang waktu tertentu atau memantau ukuran request dalam rentang waktu tertentu.
Summary

Instrumen Aplikasi Menggunakan Prometheus

Berikut ini adalah struktur folder yang akan kita gunakan untuk melakukan instrumentasi menggunakan Golang dan Docker.

Sebelum menjalankan docker compose up -d, pastikan struktur folder seperti ini.

|   docker-compose.yml
|   Dockerfile
|   go.mod
|   go.sum
|   main.go
|   prometheus.yml

Sebelum melakukan instrumentasi, kita pasang beberapa package yang dibutuhkan menggunakan

go get github.com/prometheus/client_golang/prometheus/promauto /
github.com/prometheus/client_golang/prometheus /

Misal kita punya HTTP handler sebagai berikut.

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        err := serviceA()
    })

di dalam handler kita punya fungsi serviceA, di mana fungsi tersebut akan menjalankan logika bisnis, berinteraksi dengan koneksi eksternal seperti memanggil gRPC dari servis atau melakukan HTTP call ke aplikasi lain, hingga melakukan query ke database. Untuk mengetahui berapa request yang gagal atau berhasil diolah serta berapa lama waktu yang diperlukan untuk mengolah request oleh handler tersebut, kita melakukan instrumentasi menggunakan fungsi setMeter().

// main.go

var opsProcessed *prometheus.CounterVec

var opsDuration *prometheus.HistogramVec

func setMeter() {
    opsProcessed = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "app_request_total",
            Help: "Number of total request",
        },
        []string{"URL", "status"},
    )

    opsDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name: "app_request_duration",
            Help: "Duration of a request",
        },
        []string{"URL", "status"},
    )

    prometheus.Register(opsProcessed)

    prometheus.Register(opsDuration)
}

Pada fungsi di atas, kita mendeklarasikan opsProcessed dan opsDuration sebagai metrik yang akan digunakan untuk menginstrumentasi HTTP Server. opsProcessed digunakan untuk mengukur berapa banyak request yang diproses dan opsDuration digunakan untuk mengukur berapa lama waktu yang dibutuhkan untuk menyelesaikan sebuah request. Ketika menginisialisasi kedua metrik tersebut, terdapat argumen dengan tipe data []string. Argumen ini disebut sebagai label yang berguna untuk membedakan metrik dan akan kita gunakan untuk melakukan query di Prometheus nanti. Kita bisa mendefinisikan label sesuai kebutuhan, dan dalam contoh ini kita melakukan labeling untuk path dan HTTP response code. Panduan lengkap penggunaan label bisa dilihat di sini.

Berikut keseluruhan kode yang digunakan dalam main.go

// main.go

package main

var opsProcessed *prometheus.CounterVec

var opsDuration *prometheus.HistogramVec

func setMeter() {
    opsProcessed = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "app_request_total",
            Help: "Number of total request",
        },
        []string{"URL", "status"},
    )

    opsDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name: "app_request_duration",
            Help: "Duration of a request",
        },
        []string{"URL", "status"},
    )

    prometheus.Register(opsProcessed)

    prometheus.Register(opsDuration)
}

func main() {
    setMeter()

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()

        respCode := 200

        defer func() {
            opsDuration.WithLabelValues("/", fmt.Sprint(respCode)).Observe(time.Since(start).Seconds())
        }()

        failQuery := r.URL.Query().Get("fail")

        if failQuery != "" {
            respCode = 500

            isFail, err := strconv.ParseBool(failQuery)
            if err != nil {
                w.WriteHeader(http.StatusInternalServerError)
                w.Write([]byte("error parse query"))

                log.Println("error parse query")

                opsProcessed.WithLabelValues("/", fmt.Sprint(http.StatusInternalServerError)).Inc()

                return
            }

            if isFail {
                w.WriteHeader(http.StatusInternalServerError)
                w.Write([]byte("encounter fail"))

                log.Println("encounter fail")

                opsProcessed.WithLabelValues("/", fmt.Sprint(http.StatusInternalServerError)).Inc()

                return
            }
        }

        w.Write([]byte("Hello, World!"))

        opsProcessed.WithLabelValues("/", fmt.Sprint(http.StatusOK)).Inc()
    })
    http.Handle("/metrics", promhttp.Handler())

    log.Println("Starting server on :9320")
    if err := http.ListenAndServe(":9320", nil); err != nil {
        log.Fatalf("could not start server: %v\n", err)
    }
}

Perhatikan method WithLabelValues() ketika memanggil opsProcessed maupun opsDuration. Kita mengisi argumen pada method tersebut dengan / dan response code, karena ketika kita menginisiasi opsProcessed dan opsDuration, kita mendefinisikan label URL dan status. Jika jumlah argumen method tersebut tersebut kurang atau lebih dari 2, maka akan terjadi galat (error).

Jalankan server menggunakan go run main.go, buka browser, dan arahkan ke http://localhost:9320/ atau http://localhost:9320?fail=true, setelah itu coba akses http://localhost:9320/metrics. Di endpoint metrics kita bisa melihat metrik dan label yang telah kita definisikan di fungsi setMeter() sebagai berikut.

Kita akan menggunakan Docker dan Prometheus untuk melakukan visualisasi dan query metrik yang telah kita buat.

Menggunakan Prometheus di Docker

Sebelum kita melakukan query dan membuat visualisasi, kita akan membuat Dockerfile dari aplikasi Go yang telah kita buat. Berikut Dockerfilenya.

# Dockerfile

FROM golang:1.22-alpine AS build
ARG APP_VERSION=latest

WORKDIR /src/

COPY . /src/.

RUN CGO_ENABLED=0 go build -o /bin/go-loki ./main.go

# final - service
FROM alpine as api-service

COPY --from=build /bin/go-loki /bin/go-loki

# HTTP Port
EXPOSE 9320

ENTRYPOINT ["/bin/go-loki"]

Kemudian buatlah configuration file untuk Prometheus dengan nama prometheus.yml. Kita akan mendefinisikan aplikasi apa saja yang akan di-scrape oleh Prometheus menggunakan configuration file ini. Berikut isi prometheus.yml.

# prometheus.yml

global:
  scrape_interval: 3s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: 
        - "localhost:9090"

  - job_name: app 
    metrics_path: /metrics
    static_configs:
      - targets:
        - host.docker.internal:9320

Perhatikan bagian scrape_configs.static_configs.targets. Pada bagian tersebut, kita menuliskan nilai host.docker.internal:9320, di mana nilai tersebut merujuk pada aplikasi yang telah kita Dockerize menggunakan Dockerfile. Karena kita akan menggunakan Docker untuk menjalankan Prometheus dan aplikasi, kita tidak menggunakan localhost:9320 sebagai nilai pada bagian scrape_configs.static_configs.targets, melainkan host.docker.internal:9320.

Berikutnya, buatlah file docker-compose.yml dengan isi sebagai berikut.

# docker-compose.yml

version: "3"

volumes:
  prometheus_data:

networks:
  observability:

services:
  prometheus:
    image: prom/prometheus:v2.24.0
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
      - '--web.console.templates=/usr/share/prometheus/consoles'
    ports:
      - 9090:9090
    restart: always
    networks:
      - observability

  app:
    container_name: app
    build:
      context: .
      dockerfile: ./Dockerfile
    ports:
      - 9320:9320
    networks:
      - observability

Jalankan docker compose up -d, kemudian cobalah akses http://localhost:9090/targets. Kita akan melihat app sebagai salah satu target seperti yang telah kita definisikan di bagian scrape_configs.static_configs.targets.

Kemudian, cobalah akses tab Graph yang berada di navigation bar, kita akan melihat tampilan seperti ini.

Di kolom Expression, cobalah isi app_request_total, kita akan mendapatkan hasil seperti ini.

Kita akan mendapatkan total request yang masuk ke endpoint localhost:9320 dengan response code yang berbeda. Response code 500 didapat ketika query fail pada endpoint bernilai true, dan 200 ketika bernilai false atau tidak diisi sama sekali. Kemudian, untuk mendapatkan rata-rata waktu yang dibutuhkan untuk menyelesaikan request, kita menggunakan query app_request_duration_sum / app_request_duration_count atau histogram_quantile(0.5, rate(app_request_duration_bucket[10m])). Kita akan mendapatkan hasil yang kurang lebih seperti ini di Prometheus jika kita menjalankan query di atas.

Referensi

The Last Minute Recoffeery Architecture Decision

Syukur — Mon, 19 Jun 2023 03:50:32 +0000

Agê Barros on UnsplashPhoto by Agê Barros on Unsplash

Introduction

I am a Bangkit Academy 2023 Cloud Computing cohort. Near end of our journey as Bangkit Academy cohort, we are bound to finish a capstone project. Students across Cloud Computing, Mobile Development, and Machine Learning work together to build a software that expected could give positive impact on society. Our team consists of Saddam Sinatrya Jalu Mukti, Alfatih Aditya Susanto, Arizki Putra Rahman, Dimas Ichsanul Arifin, and Ramdhan Firdaus Amelia altogether to build scalable and cost effective application. In this article, we will discuss about the background of the capstone project, initial architecture, last minute issue, last minute architecture, and how the final architecture performs.

Background

We are planned to make a coffee leaf disease detection. Our initial idea was gather the dataset (of course), looking backward about the past research and what has been achieved on current product that aims to solve the problem, then we propose our initial software architecture that will become our development guideline during development phase. On machine learning side, we will use pre-trained model to detect the leaf, while mobile development side will utilize jetpack compose to build the mobile application.

Initial Architecture

Our proposed/initial architecture as follows:

We planned to create 2 REST APIs that both of them deployed on Cloud Run, there are authentication service and image service. The authentication service is a mandatory requirement for this capstone project. The authentication service is responsible for authentication purposes such as register and login. The image service is an API that responsible for image data, such as uploading, fetching, and update the detection data from machine learning model to database.

We conduct a small research about how long the image classification task done with single data. It takes about 5 seconds to do the job. Since we do not want users to wait that long, we decided to use Cloud Pub/Sub in order to integrate image service with our machine learning. Cloud Pub/Sub enables the image service to communicate asynchronously with machine learning model, so image service does not need to wait for machine learning to finish the job. Both image service and machine learning model act as publisher and subscriber with their respective topics.

Last Minute Issue

Our planned architecture did not run well. Since our machine learning compatriots does not want to touch the deployment too much, we are facing issue when deploy machine learning model to Cloud Run. At that time, we still want to deploy the model to Cloud Run by integrating with Cloud Build by connecting to our machine learning repository, but we are having issue with Cloud Build quota. Why not integrate with Artifact Registry or Container Registry? since we are using TensorFlow it cause the image size humongous!. In short, our machine learning compatriots decided to deploy it to App Engine.

After the ML model has been deployed on App Engine, it is time to integrate image service with ML model. My initial approach is to test it with traditional HTTP request and it was successful attempt. Next, I want to integrate by utilize Cloud Pub/Sub with push subscription type.

There are 3 types of subscriptions in Cloud Pub/Sub, push, pull, and BigQuery subscripstion. We will cover push and pull scenario in this topic. In push scenario, the publisher should know the HTTP endpoint of the subscriber and the endpoint should only receive POST request. Meanwhile in pull scenario, the subscriber does not make request, instead the subscriber pull stream of messages actively from the topic.

The decision of using the push subscription is to minimize the ML compatriots effort from implementing the pull subscription type (since implementing ML model is time consuming tho). However, when I hit the endpoint, the logging from ML model/App Engine shows like this.

It return 500 HTTP status code. At this time, I was clueless why the ML model refuse the request. Turns out, when deliver message using push subscription, the Cloud Pub/Sub will store the message with given format:

{
    "message": {
        "attributes": {
            "key": "value"
        },
        "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
        "messageId": "2070443601311540",
        "message_id": "2070443601311540",
        "publishTime": "2021-02-26T19:13:55.749Z",
        "publish_time": "2021-02-26T19:13:55.749Z"
    },
   "subscription": "projects/myproject/subscriptions/mysubscription"
}

The payload or data you want to send to your subscriber lies within data. The value of your payload has been decoded to base64 by Cloud Pub/Sub client. At this point, the ML model forced to change their data layer to match the current payload.

In short, everything goes well when invoking Cloud Pub/Sub from image service to ML model, but when image service has been deployed on Cloud Run the ML model refuse the message by returning 400 HTTP code.

At this time, I am completely clueless what step should I take without changing our proposed/initial architecture.

Last Minute Architecture

After one or couple days of thinking and the deadline has near to its end, we should change our architecture in order to integrate our services and keep track on our goal to serve the prediction task asynchronously. Here is our last minute architecture.

Previously, we deploy our ML model to App Engine and use Cloud Pub/Sub with push subscription to integrate with image service. However, this approach does not work well.

On our last minute architecture, we move our ML model to Cloud Function. The trigger is whenever there are successful write dat attempt to Firestore, the ML model will retrieve the data to perform the prediction task. With this approach, everything goes well and our user does not need to wait for up to 5 seconds on their screen! :)

Architecture Performance

There are 2 performance that we could provide on this architecture: cost and latency. For cost, we expect the application to serve certain tasks that can be found here. Here is the result for the latency from image service and time execution from ML model.

With our last minute architecture, the image service able to serve the requests under 1 seconds. Meanwhile on the ML model (coded with square with blue-green-ish background), there are few certain spikes when serving the request. This due the model should load the .H5 file/model file from Cloud Storage. The load process might executed once. After certain time window without incoming request, the ML model will be shutdown and whenever there is incoming request, the ML model will repeat the step.

Membedah Multiple VPC Network Di Google Cloud

Syukur — Fri, 21 Apr 2023 01:06:00 +0000

Foto oleh Alina Grubnyak on Unsplash

Virtual Private Cloud atau VPC adalah versi virtual dari network fisik yang disediakan oleh public cloud. VPC dibangun dari subnet, di mana subnet tersebut bisa diperoleh dari subnet yang sudah ditentukan (predefined) atau subnet yang kita tentukan sendiri. Subnet tersebut didefinisikan menggunakan notasi CIDR (Classless Interdomain Routing) dengan keterangan sebagai berikut

gambar notasi CIDR Semakin tinggi angka CIDR, jumlah host atau komputer yang terhubung dalam suatu subnet akan semakin sedikit.

VPC di Google Cloud Platform (selanjutnya disebut GCP) memiliki public dan private IP. Perbedaan antara public dan private IP pada VPC adalah sebagai berikut

Public IP	Private IP
Bisa didapat dari pool (bersifat ephemeral/sementara) atau didefinisikan sendiri (bersifat statis)	Didapat dari rentang subnet pada sebuah VM menggunakan DHCP
Dapat terhubung dengan internet	Hanya bisa terhubung dengan VM

Membuat VPC Network di Google Cloud Platform

Skenario

Artikel ini ditujukan untuk membedah course tersemat yang bisa diakses di sini. Pada artikel ini, kita akan mencoba membuat 2 VPC network dengan region yang berbeda dengan network diagram sebagai berikut.

Kita akan membuat examplenet VPC dan managementnet VPC, di mana pada examplenet VPC terdapat 2 buah subnet yang masing-masing subnet memiliki sebuah VM yang akan kita buat dari compute engine, serta managementnet VPC yang memiliki sebuah VM dari compute engine.

Menginisiasi VPC Network

Untuk membuat VPC network di Google Cloud Console, pilih menu VPC Network kemudian pilih VPC networks seperti pada gambar.

Pilih Create VPC Network seperti pada gambar

Jika tampilan pada layar sudah seperti ini, isi form dengan nilai/value sebagai berikut.

Value untuk mangementnet

Field	Value
Name	managementnet
Subnet creation mode	custom
Name (New subnet)	managementnetsubnet-asiasoutheast
Region	asia-southeast2
IPv4 range	10.173.0.0/20

Klik tombol Create berwarna biru

Value untuk examplenet

Field	Value
Name	examplenet
Subnet creation mode	custom
Name (New subnet)	examplenetsubnet-asiasoutheast
Region	asia-southeast2
IPv4 range	10.120.0.0/20

untuk menambahkan subnet examplenetsubnet-asiaeast, klik add subnet, lalu isi value sebagai berikut

Field	Value
Name (New subnet)	examplenetsubnet-asiaeast
Region	asia-east2
IPv4 range	10.130.0.0/21

Klik tombol Create berwarna biru

Periksa kembali apakah VPC network kita sudah berhasil diinisiasi atau belum dengan melihat di dashboard VPC network. Kurang lebih ketika kita sudah menjalankan langkah-langkah di atas, tampilan halaman dashboard kita akan sebagai berikut.

Jika teman-teman penasaran dengan range IPv4 yang bisa digunakan sebagai subnet dalam VPC, teman-teman bisa membaca lebih lanjut di sini

Membuat Firewall

Firewall untuk apa?. Kegunaan firewall pada artikel ini supaya kita bisa mengakses port VM yang kita buat. Untuk membuat firewall, teman-teman bisa mengakses menu seperti di gambar berikut.

Setelah muncul halaman dashboard pilih Create Firewall Rules

Kemudian, isi field dengan value sebagai berikut.

Field	Value
Name	examplenet-allow-icmp-ssh-rdp
Network	examplenet
Direction of Traffic	Ingress
Targets	All instances in the network
Source IPv4 Address	0.0.0.0/0
Specified Protocols and Ports	Centang TCP dan isi port 22 dan port 3389, serta centang others dan isi dengan protokol ICMP

Klik tombol Create berwarna biru

Buat satu lagi firewall rules dengan isi field dengan value sebagai berikut.

Field	Value
Name	examplenetmanagement-allow-icmp-ssh-rdp
Network	examplenetmanagement
Direction of Traffic	Ingress
Targets	All instances in the network
Source IPv4 Address	0.0.0.0/0
Specified Protocols and Ports	Centang TCP dan isi port 22 dan port 3389, serta centang others dan isi dengan protokol ICMP

Klik tombol Create berwarna biru

Mari kita coba bedah firewal rules yang telah kita buat.

Ketika kita membuat firewall rule, kita harus memiliki nama untuk rule tersebut dan nama tersebut haruslah bersifat unik.
Setiap network atau VPC network bisa memiliki lebih dari satu firewall rules, silakan teman-teman coba membuat firewall rule yang lain untuk examplenetmanagement VPC atau examplenet VPC.
Kita bisa mengatur apakah firewall rule yang kita buat diterapkan untuk data yang masuk ke dalam atau keluar VPC network kita dengan memilih ingress untuk data yang masuk dan egress untuk data yang keluar.
Setiap firewall rule memiliki target di mana target tersebut akan diterapkan pada VPC network kita. Jika teman-teman mengklik dropdown target, teman-teman akan menemukan pilihan All instances in the network, Specified target tags, dan * Specified service account*. Pilih All instances in the network jika teman-teman ingin firewall rule tersebut diterapkan pada seluruh instance atau komputasi yang menerapkan firewall rule tersebut (atau VPC network yang terhubung menggunakan firewall rule tersebut), gunakan Specified target tags jika ingin menerapkan sebuah atau beberapa tags pada instance atau komputasi yang menerapkan firewall rule tersebut (atau VPC network yang terhubung menggunakan firewall rule tersebut), dan gunakan Specified service account jika ingin menerapkan sebuah atau beberapa service account pada instance atau komputasi yang menerapkan firewall rule tersebut (atau VPC network yang terhubung menggunakan firewall rule tersebut). Kali ini kita menggunakan All instances in the network yang akan kita terapkan ketika kita membuat VM instance nanti.
Sama seperti target, kita juga bisa memilih apakah firewall rule yang kita buat akan diterapkan pada rentang IPv4, rentang IPv6, atau berdasarkan service account tertentu dengan mengisi Source field. Pada artikel ini, kita mengisi Source field dengan rentang alamat IPv4 0.0.0.0/0 yang artinya seluruh subnet pada VPC network akan menerapkan firewall rule ini.
Firewall rule yang kita terapkan memungkinkan kita berkomunikasi kepada instance yang menerapkan firewall rule tersebut. Pada artikel ini, kita mengizinkan port 22 untuk melakukan SSH, port 3389 untuk RDP, serta protokol ICMP untuk memeriksa apakah ada error ketika kita mengirim data.

Jika langkah-langkah di atas sudah kita jalankan, di dashboard firewall rules kita kurang lebih akan seperti ini.

Membuat Compute Engine Instances

Langkah selanjutnya adalah membuat compute engine instaces dengan mengakses menu seperti di gambar.

Jika sudah muncul dasboard Compute Engine, klik Create Instance, kemudian isi field serta value-nya sebagai berikut.

Instance examplemanagementnet-asiasoutheast-vm

Field	Value
Name	examplemanagementnet-asiasoutheast-vm
Region	asia-southeast, untuk Zone, pilih asia-southeast2-a
Series	E2 dengan Machine type e2-micro

Pergi ke bagian Advanced Options, kemudian pilih bagian Networking. Isi field dengan value sebagai berikut.

Field	Value
Network	examplenetmanagement
Subnetwork	managementsubnet-asiasoutheast

Klik tombol Create berwarna biru

Instance examplenet-asiaeast-vm

Field	Value
Name	examplenet-asiaeast-vm
Region	asia-east, untuk Zone, pilih asia-east2-c
Series	E2 dengan Machine type e2-micro

Pergi ke bagian Advanced Options, kemudian pilih bagian Networking. Isi field dengan value sebagai berikut.

Field	Value
Network	examplenet
Subnetwork	examplesubnet-asiaeast

Klik tombol Create berwarna biru

Instance examplenet-asiasoutheast-vm

Field	Value
Name	examplenet-asiasoutheast-vm
Region	asia-southeast, untuk Zone, pilih asia-southeast2-a
Series	E2 dengan Machine type e2-micro

Pergi ke bagian Advanced Options, kemudian pilih bagian Networking. Isi field dengan value sebagai berikut.

Field	Value
Network	examplenet
Subnetwork	examplesubnet-asiasoutheast

Klik tombol Create berwarna biru

Instance vm-manager

Field	Value
Name	vm-manager
Region	asia-southeast, untuk Zone, pilih asia-southeast2-a
Series	E2 dengan Machine type e2-small

Pergi ke bagian Advanced Options, kemudian pilih bagian Networking. Untuk instance ini, kita akan menghubungkan 2 VPC network menggunakan 2 buah network interface. Isi field dengan value sebagai berikut.

Field	Value
Network	examplenet
Subnetwork	examplesubnet-asiasoutheast

Klik Add Network Interface, kemudian isi lagi form dengan value sebagai berikut.

Field	Value
Network	examplemanagementnet
Subnetwork	managementsubnet-asiasoutheast

Klik tombol Create berwarna biru

Jika langkah-langkah di atas sudah kita tempuh, kita akan mendapatkan tampilan pada dashboard Compute Engine sebagai berikut.

Memeriksa Koneksi Antar VPC

Mari kita bereksperimen apakah VPC yang kita terapkan pada network interface di instance kita memungkinkan seluruh instance kita terhubung satu sama lain. Perhatikan dashboard Compute Engine teman-teman. Teman-teman bisa melihat internal IP dan external IP yang menempel pada setiap instance. Di sebelah external IP, ada SSH yang akan kita gunakan untuk menguji konektivitas dari setiap instance yang kita buat.

Pertama, tekan SSH pada instance examplenet-asiaeast-vm, kemudian gunakan perintah di bawah ini untuk menguji apakah instance tersebut terhubung dengan instance examplenet-asiasoutheast-vm menggunakan external IP dari instance examplenet-asiasoutheast-vm.

ping -c 3 <alamat external IP examplenet-asiasoutheast-vm>

Kita berhasil melakukan ping dari instance examplenet-asiaeast-vm ke instance examplenet-asiasoutheast-vm. Sekarang cobalah untuk melakukan ping dari instance examplenet-asiaeast-vm ke instance examplenet-asiasoutheast-vm menggunakan internal IP dari instance examplenet-asiasoutheast-vm menggunakan potongan perintah di bawah.

ping -c 3 <alamat internal IP examplenet-asiasoutheast-vm>

Kita juga berhasil melakukan ping dari instance examplenet-asiaeast-vm ke instance examplenet-asiasoutheast-vm. Hal ini dikarenakan instance examplenet-asiaeast-vm dan instance examplenet-asiasoutheast-vm masih satu VPC network, yaitu examplenet, walaupun mereka berada pada subnet yang berbeda.

Sekarang, cobalah melakukan ping dari instance examplenet-asiaeast-vm ke instance examplemanagementnet-asiasoutheast-vm menggunakan external IP dari instance examplemanagementnet-asiasoutheast-vm. Kita juga berhasil melakukan pingdari instance examplenet-asiaeast-vm ke instance examplemanagementnet-asiasoutheast-vm.

Kemudian, cobalah untuk melakukan ping dari instance examplenet-asiaeast-vm ke instance examplemanagementnet-asiasoutheast-vm menggunakan internal IP dari instance examplemanagementnet-asiasoutheast-vm. Jika kita lihat di terminal, tidak ada data yang berhasil terkirim. Hal ini disebabkan instance examplemanagementnet-asiasoutheast-vm berada di VPC network yang berbeda dengan instance examplemanagementnet-asiasoutheast-vm.

Terakhir, cobalah melakukan ping dari instance vm-manager ke instance examplenet-asiaeast-vm menggunakan internal IP dari instance examplenet-asiaeast-vm. Kita tidak akan mendapatkan respons dari instance examplenet-asiaeast-vm, karena network interface dari instance vm-manager (eth0) tersambung dengan instance examplenet-asiasoutheast-vm.

Rangkuman

Pada artikel ini, kita telah sama-sama membahas apa itu VPC network, public IP, static IP, serta kegunaan dari VPC network di Google Cloud. Selain itu, kita juga mencoba membuat dan menguji konektivitas antar VM instance menggunakan internal IP address maupun external IP address dari masing-masing VM instance. Hasilnya, kita bisa melakukan ping untuk instance yang masih berada dalam satu subnet dan kita juga bisa melakukan ping untuk instance yang network interface nya terhubung dengan salah satu instance pada suatu subnetwork.

Referensi

https://cloud.google.com/vpc/docs/vpc
https://www.cloudskillsboost.google/catalog_lab/1031

Implementasi gRPC Di Golang Dan Windows

Syukur — Fri, 27 Jan 2023 10:35:47 +0000

Foto oleh Steve Johnson dari Unsplash

Tentang RPC

Pada proses pengembangan aplikasi, proses mengintegrasikan komponen-komponen seperti database maupun sistem eksternal menjadi salah satu bagian yang sulit dipisahkan. Proses integrasi ini lazimnya menggunakan API (Application Programming Interface) dari database atau sistem eksternal tertentu. Misalnya, ketika ingin mengintegrasikan database MySQL, kita perlu mengetahui perintah-perintah yang telah disediakan oleh MySQL baik lewat CLI (Command Line Interface) atau database connector dari bahasa pemrograman yang kita gunakan supaya kita bisa memanipulasi data di dalam database tersebut.

Cara lain yang lebih populer untuk mengintegrasikan aplikasi adalah menggunakan RPC atau HTTP/JSON API. RPC bisa digunakan untuk mengintegrasikan aplikasi jika performa menjadi pertimbangan, serta kita memiliki kendali penuh terhadap prosedur dari service yang kita kelola, sedangkan HTTP/JSON API digunakan jika aplikasi yang dikembangkan memperimbangkan kemudahan proses pengembangan serta aplikasi tersebut memiliki rencana untuk dikembangkan oleh orang lain di masa depan.

Tentang gRPC

gRPC merupakan RPC framework yang dikembangkan oleh Google. Seperti RPC pada umumnya, gRPC bekerja seperti memanggil fungsi atau prosedur dari suatu mesin oleh mesin lain secara remote.

gRPC menggunakan protobuf atau protocol buffer sebagai format atau kontrak yang digunakan untuk berkomunikasi antara client/stub dengan server. Isi dari file protobuf ini adalah service yang merupakan method yang akan dipanggil oleh client, serta message yang merupakan data atau parameter yang diterima oleh service. File protobuf ini harus di-compile ke dalam bahasa pemrograman yang ingin kita gunakan. Pada gambar di atas, dengan menggunakan file protobuf yang sama, gRPC server yang ditulis menggunakan bahasa C++ bisa berkomunikasi dengan gRPC client yang ditulis menggunakan bahasa Java atau Ruby.

Ada beberapa daur hidup atau life cycle penggunaan gRPC yang bisa kita gunakan, diantaranya :

Unary : Proses ini berjalan satu arah, di mana client akan memanggil method/service pada server, dan server akan mengembalikan response jika service tersebut selesai diproses.
Server/Client Streaming : Proses ini bisa berjalan baik di sisi server atau client, dan proses ini mirip dengan unary. Hanya saja, data yang dikirim oleh server atau client dikirim secara kontinu/streaming hingga tidak ada yang bisa dikirim data dari server atau client.
Bidirectional Streaming : Proses ini berjalan secara dua arah, di mana baik server atau client akan mengirim data hingga tidak ada data yang bisa dikirim atau salah satu dari server atau client menghentikan proses pengiriman data.

Praktik

Mengunduh Protobuf Compiler

Hal pertama yang perlu dipersiapkan adalah protobuf compiler. Compiler tersebut berguna untuk men-generate kode bahasa pemrograman dari file .proto yang kita buat. Teman-teman bisa mengunjungi tautan ini untuk mengunduh compiler protobuf berdasarkan operating system yang teman-teman gunakan. Artikel ini menggunakan protobuf compiler untuk windows 64 bit versi 3.21.12.

Setelah teman-teman berhasil mengunduh protobuf compiler dan mengekstrak file zip tersebut, langkah selanjutnya adalah menambahkan path folder bin protobuf compiler yang telah diunduh ke environment variable. Folder bin yang dimaksud adalah seperti ini.

Copy path executable file tersebut, lalu paste ke Path pada environment. Untuk menambahkan path executable file protobuf compiler ke environment variable, silakan teman-teman bisa cari Edit the system and environment variable di search bar windows teman-teman. Kemudian pilih Path pada bagian User variables for admin, tekan New, dan paste path bin folder protobuf compiler. Langkah-langkah tersebut seperti ini.

Untuk memeriksa apakah protobuf compiler sudah terpasang dengan benar, silakan teman-teman buka cmd dan ketik protoc. Jika protobuf compiler sudah terpasang dengan benar, maka tampilannya akan seperti ini.

Implementasi

Silakan teman-teman buat project/folder baru dengan struktur seperti ini.

Pada file student.proto, kita akan menuliskan message serta service yang akan di-generate oleh protobuf compiler. Isi file student.proto tersebut sebagai berikut.

syntax = "proto3";

option go_package = "./../pb";

import "google/protobuf/empty.proto";

package pb;

message StudentRequest{
    string name = 1;
    int32 id = 2;
}

service Students{
    rpc RegisterStudent(StudentRequest) returns (google.protobuf.Empty);
}

Maksud dari file proto di atas dijelaskan pada tabel di bawah.

Potongan Kode	Penjelasan
`syntax = "proto3";`	Menentukan versi protobuf yang digunakan. Pada contoh ini, versi yang digunakan adalah versi 3
`option go_package = "./../pb";`	Menentukan di mana file protobuf yang di-generate oleh protobuf compiler akan di simpan. Pada contoh ini, seluruh generated file protobuf akan disimpan di dalam folder `pb` yang letaknya relatif terhadap lokasi file `.proto`
`import "google/protobuf/empty.proto";`	Melakukan import file proto dari package/folder lain
`package pb;`	Menentukan nama package dari file proto yang di-generate oleh protobuf compiler
`message StudentRequest{}`	Mendefinisikan message/payload yang akan digunakan. Setelah file proto berhasil di-generate, untuk bahasa `Go`, protobuf compiler akan membuat struct dengan nama `StudentRequest`
`service Students{}`	Mendefinisikan procedure/service yang akan dipanggil/invoke. Protobuf compiler akan men-generate interface `StudentServer` dan `StudentClient` dengan isi interface berupa method yang didefinisikan di dalam `service Students{}`
`rpc RegisterStudent(StudentRequest) returns (google.protobuf.Empty);`	Mendefiniskan method/contract yang akan digunakan oleh client dan server. Protobuf compiler akan men-generate method `RegisterStudent` yang akan di-implement oleh `StudentServer` dan `StudentClient`

Untuk menghasilkan generated file, kita perlu meng-ompile file proto di atas dengan command sebagai berikut :

protoc --go_out=. --go-grpc_out=. *.proto

Perintah di atas dijalankan pada direktori di mana file proto berada. Gambar di bawah ini menunjukkan file proto yang berhasil dikompilasi.

Implementasi Dalam Golang

File proto yang telah dikompilasi kemudian bisa digunakan menggunakan bahasa pemrograman yang didukung oleh gRPC dan Protobuf (bahasa pemrograman yang didukung gRPC bisa dilihat di sini dan bahasa pemrograman yang didukung Protocol BUffer bisa dilihat di sini).

Di dalam file student_grpc.pb.go, kita akan menemukan interface sebagai berikut :

type StudentsClient interface {
    RegisterStudent(ctx context.Context, in *StudentRequest, opts ...grpc.CallOption) (*emptypb.Empty, error)
}
...
type StudentsServer interface {
    RegisterStudent(context.Context, *StudentRequest) (*emptypb.Empty, error)
    mustEmbedUnimplementedStudentsServer()
}

Interface StudentsServer dan StudentsClient merupakan service Students{} dan method RegisterStudent merupakan rpc RegisterStudent yang di-generate oleh file proto yang telah kita buat. Interface tersebut harus kita implementasi baik di client atau server kita. Pada artikel ini, kita akan mengimplementasi StudentServer. Implementasi tersebut kita tulis dalam file server/main.go

package main

import (
    "context"
    "go-grpc-unary/common/pb"
    "log"
    "net"
    "os"
    "os/signal"
    "syscall"

    "google.golang.org/grpc"
    "google.golang.org/protobuf/types/known/emptypb"
)

type Server struct {
    pb.UnimplementedStudentsServer
}

const PORT = ":9000"

func (s *Server) RegisterStudent(ctx context.Context, in *pb.StudentRequest) (*emptypb.Empty, error) {
    log.Println(in.Name)
    log.Println(in.Id)
    return new(emptypb.Empty), nil
}

func initGrpcServer() {
    l, err := net.Listen("tcp", PORT)
    if err != nil {
        log.Fatalf("unable to create tcp connection at port %v with error %v \n", PORT, err)
    }

    srv := grpc.NewServer()
    pb.RegisterStudentsServer(srv, &Server{})
    srv.Serve(l)
}

func main() {
    done := make(chan os.Signal, 1)
    signal.Notify(done, syscall.SIGINT, syscall.SIGTERM)
    go initGrpcServer()
    <-done
}

Pengujian Menggunakan Postman

Pada artikel ini, kita akan menggunakan Postman untuk menguji gRPC endpoint yang telah kita buat.

Pertama, kita perlu membuat gRPC Request seperti pada gambar.

Kemudian, kita melakukan import file proto yang telah kita definisikan. Perhatikan bagian Import paths yang ditandai merah. Bagian tersebut kita isi dengan path di mana kita meng-import file proto lain pada file proto yang kita tulis. Pada file proto, kita menuliskan import "google/protobuf/empty.proto";, di mana kita meng-import file empty.proto. File tersebut merupakan file bawaan dari protobuf yang terletak di dalam folder include/google/protobuf (silakan kembali ke bagian Mengunduh Protocol Buffer untuk mengetahui lokasi folder tersebut).

Kemudian, pilih save without importing untuk menyelesaikan proses import file proto.

Isikan server URL dengan localhost:9000. Pada bagian Select a method, kita dapat melihat gRPC contract/method yang telah kita definisikan di file proto, pada hal ini rpc RegisterStudent. Pilih method tersebut, dan isikan data yang akan dikirim menggunakan Generate Example Message.

Jalankan server di direktori server/main.go menggunakan go run main.go pada direktori tersebut, kemudian Invoke method RegisterStudent. Jika Status code adalah 0, berarti data tersebut berhasil diterima oleh server. Jika kita melihat logging dari server/main.go, kita akan melihat data yang dikirim dari Postman.

logging server/main.go

2023/01/27 11:04:43 magna
2023/01/27 11:04:43 -279401480

Rangkuman

Pada artikel ini, kita telah belajar apa itu gRPC, Protocol Buffer, cara membuat file protobuf, mengompilasi file protobuf, mengimplementasi dalam bahasa Go, serta menguji menggunakan Postman. Banyak hal yang tidak dibahas di artikel ini. Penulis merekomendasikan teman-teman untuk membaca tentang server streaming, client streaming, bidirectional streaming, serta cara lain mendefinisikan message di file protobuf

Referensi

https://cloud.google.com/blog/products/api-management/understanding-grpc-openapi-and-rest-and-when-to-use-them
https://developers.google.com/protocol-buffers/docs/reference/overview
https://grpc.io/docs/

Designing Single Page App To Promote Tourism Post-Pandemic At Jambuwer Village

Syukur — Fri, 11 Nov 2022 10:31:16 +0000

Background

When the pandemic hit, many economic sectors were affected, one of them was the tourism sector. Recovering the sector after the pandemic is a challenge for every tourism service provider. There are many ways to meet this challenge. One way -- and the cheapest -- is to promote in digital media such as web applications. Through this community service, I am trying to build a web application for Jambuwer village to promote Jambuwer village as a tourism village, helping economic agents, and promote the existing culture and local wisdom.

Methodology

In this application design, the methodology used is waterfall. The main reason for choosing this methodology is that it is suitable for implementation for small-scale teams and small projects. Here is the methodology diagram.

Regardless of how someone using waterfall methodology, the methodology is running sequentially, and often consists of these steps (Bassil, 2012) :

Analysis
Is a steps to not only gather information about software specification and behavior, but also formulating how this software could achieve the business case
Design
After the expected software specification and behavior are met, the following step is to plan how the software will be built. During this step, the user interface, database, and software architecture will be decided.
Implementation
This refers to realization of software requirement and design in form of executable program.
Testing
This step also known as verification and validation of the executable program against the software requirement. This step also aims for generating the software performance through specific metric.
Maintenance
After the executable program is passed the testing and the decision to release from development environment to production environment were made, the next step is to keep the program stable against various condition on production environment. During this step, the metrics are being watched over time. In case there are unusual behavior from system against user activity, the action to fix the system will be made.

Result

The result from this application design is a single page app (SPA) that built using Bootstrap. We use https://github.com/StartBootstrap/startbootstrap-creative as the template in order to decrease the time development. Moreover, there are not much content to be load and not much user interaction to be implemented. Hence we thought, the template is enough.

The application has been deployed to GitHub page that you can find it here