github.com/gravitational/teleport/api@v0.0.0-20240507183017-3110591cbafc/types/events/api.go (about)

     1  /*
     2  Copyright 2021 Gravitational, Inc.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  // Package events contains event related types and logic required by the Teleport API.
    18  package events
    19  
    20  import (
    21  	"context"
    22  	"time"
    23  )
    24  
    25  // ProtoMarshaler implements marshaler interface
    26  type ProtoMarshaler interface {
    27  	// Size returns size of the object when marshaled
    28  	Size() (n int)
    29  
    30  	// MarshalTo marshals the object to sized buffer
    31  	MarshalTo(dAtA []byte) (int, error)
    32  }
    33  
    34  // AuditEvent represents an audit event.
    35  type AuditEvent interface {
    36  	// ProtoMarshaler implements efficient
    37  	// protobuf marshaling methods
    38  	ProtoMarshaler
    39  
    40  	// GetID returns unique event ID
    41  	GetID() string
    42  	// SetID sets unique event ID
    43  	SetID(id string)
    44  
    45  	// GetCode returns event short diagnostic code
    46  	GetCode() string
    47  	// SetCode sets unique event diagnostic code
    48  	SetCode(string)
    49  
    50  	// GetType returns event type
    51  	GetType() string
    52  	// SetType sets unique type
    53  	SetType(string)
    54  
    55  	// GetTime returns event time
    56  	GetTime() time.Time
    57  	// SetTime sets event time
    58  	SetTime(time.Time)
    59  
    60  	// GetIndex gets event index - a non-unique
    61  	// monotonically incremented number
    62  	// in the event sequence
    63  	GetIndex() int64
    64  	// SetIndex sets event index
    65  	SetIndex(idx int64)
    66  
    67  	// GetClusterName returns the name of the teleport cluster
    68  	// as set on the event.
    69  	GetClusterName() string
    70  	// SetClusterName sets the name of the teleport cluster on the event.
    71  	SetClusterName(string)
    72  }
    73  
    74  // Emitter emits audit events.
    75  type Emitter interface {
    76  	// EmitAuditEvent emits a single audit event.
    77  	//
    78  	// NOTE: when implementing this interface, the context should have
    79  	// its cancel stripped via `context.WithoutCancel`
    80  	EmitAuditEvent(context.Context, AuditEvent) error
    81  }
    82  
    83  // PreparedSessionEvent is an event that has been prepared by
    84  // a [github.com/gravitational/teleport/lib/events.SessionEventPreparer].
    85  // More specifically, it is a wrapper around an AuditEvent that signifies
    86  // the event has been prepared and is ready to be recorded or emitted.
    87  type PreparedSessionEvent interface {
    88  	GetAuditEvent() AuditEvent
    89  }
    90  
    91  // Stream is used to create continuous ordered sequence of events
    92  // associated with a session.
    93  type Stream interface {
    94  	// RecordEvent records a single session event if session recording is enabled.
    95  	RecordEvent(ctx context.Context, event PreparedSessionEvent) error
    96  	// Status returns channel broadcasting updates about the stream state:
    97  	// last event index that was uploaded and the upload ID
    98  	Status() <-chan StreamStatus
    99  	// Done returns channel closed when streamer is closed
   100  	// should be used to detect sending errors
   101  	Done() <-chan struct{}
   102  	// Complete closes the stream and marks it finalized,
   103  	// releases associated resources, in case of failure,
   104  	// closes this stream on the client side
   105  	Complete(ctx context.Context) error
   106  	// Close flushes non-uploaded flight stream data without marking
   107  	// the stream completed and closes the stream instance
   108  	Close(ctx context.Context) error
   109  }