account_events.go raw
1 package linodego
2
3 import (
4 "context"
5 "encoding/json"
6 "time"
7
8 "github.com/linode/linodego/internal/duration"
9 "github.com/linode/linodego/internal/parseabletime"
10 )
11
12 // Event represents an action taken on the Account.
13 type Event struct {
14 // The unique ID of this Event.
15 ID int `json:"id"`
16
17 // Current status of the Event, Enum: "failed" "finished" "notification" "scheduled" "started"
18 Status EventStatus `json:"status"`
19
20 // The action that caused this Event. New actions may be added in the future.
21 Action EventAction `json:"action"`
22
23 // A percentage estimating the amount of time remaining for an Event. Returns null for notification events.
24 PercentComplete int `json:"percent_complete"`
25
26 // The rate of completion of the Event. Only some Events will return rate; for example, migration and resize Events.
27 Rate *string `json:"rate"`
28
29 // If this Event has been read.
30 Read bool `json:"read"`
31
32 // If this Event has been seen.
33 Seen bool `json:"seen"`
34
35 // The estimated time remaining until the completion of this Event. This value is only returned for in-progress events.
36 TimeRemaining *int `json:"-"`
37
38 // The username of the User who caused the Event.
39 Username string `json:"username"`
40
41 // Detailed information about the Event's entity, including ID, type, label, and URL used to access it.
42 Entity *EventEntity `json:"entity"`
43
44 // Detailed information about the Event's secondary or related entity, including ID, type, label, and URL used to access it.
45 SecondaryEntity *EventEntity `json:"secondary_entity"`
46
47 // When this Event was created.
48 Created *time.Time `json:"-"`
49
50 // Provides additional information about the event.
51 Message string `json:"message"`
52
53 // The total duration in seconds that it takes for the Event to complete.
54 Duration float64 `json:"duration"`
55
56 // The maintenance policy configured by the user for the event.
57 // NOTE: MaintenancePolicySet can only be used with v4beta.
58 MaintenancePolicySet string `json:"maintenance_policy_set"`
59
60 // Describes the nature of the event (e.g., whether it is scheduled or emergency).
61 Description string `json:"description"`
62
63 // The origin of the event (e.g., platform, user).
64 Source string `json:"source"`
65
66 // Scheduled start time for the event.
67 NotBefore *time.Time `json:"-"`
68
69 // The actual start time of the event.
70 StartTime *time.Time `json:"-"`
71
72 // The actual completion time of the event.
73 CompleteTime *time.Time `json:"-"`
74 }
75
76 // EventAction constants start with Action and include all known Linode API Event Actions.
77 type EventAction string
78
79 // EventAction constants represent the actions that cause an Event. New actions may be added in the future.
80 const (
81 ActionAccountUpdate EventAction = "account_update"
82 ActionAccountSettingsUpdate EventAction = "account_settings_update"
83 ActionBackupsEnable EventAction = "backups_enable"
84 ActionBackupsCancel EventAction = "backups_cancel"
85 ActionBackupsRestore EventAction = "backups_restore"
86 ActionCommunityQuestionReply EventAction = "community_question_reply"
87 ActionCommunityLike EventAction = "community_like"
88 ActionCreditCardUpdated EventAction = "credit_card_updated"
89 ActionDatabaseCreate EventAction = "database_create"
90 ActionDatabaseDegraded EventAction = "database_degraded"
91 ActionDatabaseDelete EventAction = "database_delete"
92 ActionDatabaseFailed EventAction = "database_failed"
93 ActionDatabaseUpdate EventAction = "database_update"
94 ActionDatabaseResize EventAction = "database_resize"
95 ActionDatabaseCreateFailed EventAction = "database_create_failed"
96 ActionDatabaseUpdateFailed EventAction = "database_update_failed"
97 ActionDatabaseBackupCreate EventAction = "database_backup_create"
98 ActionDatabaseBackupRestore EventAction = "database_backup_restore"
99 ActionDatabaseCredentialsReset EventAction = "database_credentials_reset"
100 ActionDiskCreate EventAction = "disk_create"
101 ActionDiskDelete EventAction = "disk_delete"
102 ActionDiskUpdate EventAction = "disk_update"
103 ActionDiskDuplicate EventAction = "disk_duplicate"
104 ActionDiskImagize EventAction = "disk_imagize"
105 ActionDiskResize EventAction = "disk_resize"
106 ActionDNSRecordCreate EventAction = "dns_record_create"
107 ActionDNSRecordDelete EventAction = "dns_record_delete"
108 ActionDNSRecordUpdate EventAction = "dns_record_update"
109 ActionDNSZoneCreate EventAction = "dns_zone_create"
110 ActionDNSZoneDelete EventAction = "dns_zone_delete"
111 ActionDNSZoneUpdate EventAction = "dns_zone_update"
112 ActionDNSZoneImport EventAction = "dns_zone_import"
113 ActionEntityTransferAccept EventAction = "entity_transfer_accept"
114 ActionEntityTransferCancel EventAction = "entity_transfer_cancel"
115 ActionEntityTransferCreate EventAction = "entity_transfer_create"
116 ActionEntityTransferFail EventAction = "entity_transfer_fail"
117 ActionEntityTransferStale EventAction = "entity_transfer_stale"
118 ActionFirewallCreate EventAction = "firewall_create"
119 ActionFirewallDelete EventAction = "firewall_delete"
120 ActionFirewallDisable EventAction = "firewall_disable"
121 ActionFirewallEnable EventAction = "firewall_enable"
122 ActionFirewallUpdate EventAction = "firewall_update"
123 ActionFirewallDeviceAdd EventAction = "firewall_device_add"
124 ActionFirewallDeviceRemove EventAction = "firewall_device_remove"
125 ActionFirewallRuleSetCreate EventAction = "firewall_ruleset_create"
126 ActionFirewallRuleSetUpdate EventAction = "firewall_ruleset_update"
127 ActionFirewallRuleSetDelete EventAction = "firewall_ruleset_delete"
128 ActionFirewallRuleSetFirewallUpdate EventAction = "firewall_ruleset_firewall_update"
129 ActionHostReboot EventAction = "host_reboot"
130 ActionImageDelete EventAction = "image_delete"
131 ActionImageUpdate EventAction = "image_update"
132 ActionImageUpload EventAction = "image_upload"
133 ActionIPAddressUpdate EventAction = "ipaddress_update"
134 ActionLassieReboot EventAction = "lassie_reboot"
135 ActionLinodeAddIP EventAction = "linode_addip"
136 ActionLinodeBoot EventAction = "linode_boot"
137 ActionLinodeClone EventAction = "linode_clone"
138 ActionLinodeCreate EventAction = "linode_create"
139 ActionLinodeDelete EventAction = "linode_delete"
140 ActionLinodeUpdate EventAction = "linode_update"
141 ActionLinodeDeleteIP EventAction = "linode_deleteip"
142 ActionLinodeMigrate EventAction = "linode_migrate"
143 ActionLinodeMigrateDatacenter EventAction = "linode_migrate_datacenter"
144 ActionLinodeMigrateDatacenterCreate EventAction = "linode_migrate_datacenter_create"
145 ActionLinodeMutate EventAction = "linode_mutate"
146 ActionLinodeMutateCreate EventAction = "linode_mutate_create"
147 ActionLinodePowerOffOn EventAction = "linode_poweroff_on"
148 ActionLinodeReboot EventAction = "linode_reboot"
149 ActionLinodeRebuild EventAction = "linode_rebuild"
150 ActionLinodeResize EventAction = "linode_resize"
151 ActionLinodeResizeCreate EventAction = "linode_resize_create"
152 ActionLinodeShutdown EventAction = "linode_shutdown"
153 ActionLinodeSnapshot EventAction = "linode_snapshot"
154 ActionLinodeConfigCreate EventAction = "linode_config_create"
155 ActionLinodeConfigDelete EventAction = "linode_config_delete"
156 ActionLinodeConfigUpdate EventAction = "linode_config_update"
157 ActionLishBoot EventAction = "lish_boot"
158 ActionLKENodeCreate EventAction = "lke_node_create"
159 ActionLKEControlPlaneACLCreate EventAction = "lke_control_plane_acl_create"
160 ActionLKEControlPlaneACLUpdate EventAction = "lke_control_plane_acl_update"
161 ActionLKEControlPlaneACLDelete EventAction = "lke_control_plane_acl_delete"
162 ActionLongviewClientCreate EventAction = "longviewclient_create"
163 ActionLongviewClientDelete EventAction = "longviewclient_delete"
164 ActionLongviewClientUpdate EventAction = "longviewclient_update"
165 ActionManagedDisabled EventAction = "managed_disabled"
166 ActionManagedEnabled EventAction = "managed_enabled"
167 ActionManagedServiceCreate EventAction = "managed_service_create"
168 ActionManagedServiceDelete EventAction = "managed_service_delete"
169 ActionNodebalancerCreate EventAction = "nodebalancer_create"
170 ActionNodebalancerDelete EventAction = "nodebalancer_delete"
171 ActionNodebalancerUpdate EventAction = "nodebalancer_update"
172 ActionNodebalancerConfigCreate EventAction = "nodebalancer_config_create"
173 ActionNodebalancerConfigDelete EventAction = "nodebalancer_config_delete"
174 ActionNodebalancerConfigUpdate EventAction = "nodebalancer_config_update"
175 ActionNodebalancerFirewallModificationSuccess EventAction = "nodebalancer_firewall_modification_success"
176 ActionNodebalancerFirewallModificationFailed EventAction = "nodebalancer_firewall_modification_failed"
177 ActionNodebalancerNodeCreate EventAction = "nodebalancer_node_create"
178 ActionNodebalancerNodeDelete EventAction = "nodebalancer_node_delete"
179 ActionNodebalancerNodeUpdate EventAction = "nodebalancer_node_update"
180 ActionOAuthClientCreate EventAction = "oauth_client_create"
181 ActionOAuthClientDelete EventAction = "oauth_client_delete"
182 ActionOAuthClientSecretReset EventAction = "oauth_client_secret_reset" //#nosec G101
183 ActionOAuthClientUpdate EventAction = "oauth_client_update"
184 ActionOBJAccessKeyCreate EventAction = "obj_access_key_create"
185 ActionOBJAccessKeyDelete EventAction = "obj_access_key_delete"
186 ActionOBJAccessKeyUpdate EventAction = "obj_access_key_update"
187 ActionPaymentMethodAdd EventAction = "payment_method_add"
188 ActionPaymentSubmitted EventAction = "payment_submitted"
189 ActionPasswordReset EventAction = "password_reset"
190 ActionPlacementGroupCreate EventAction = "placement_group_create"
191 ActionPlacementGroupUpdate EventAction = "placement_group_update"
192 ActionPlacementGroupDelete EventAction = "placement_group_delete"
193 ActionPlacementGroupAssign EventAction = "placement_group_assign"
194 ActionPlacementGroupUnassign EventAction = "placement_group_unassign"
195 ActionPlacementGroupBecameNonCompliant EventAction = "placement_group_became_non_compliant"
196 ActionPlacementGroupBecameCompliant EventAction = "placement_group_became_compliant"
197 ActionProfileUpdate EventAction = "profile_update"
198 ActionStackScriptCreate EventAction = "stackscript_create"
199 ActionStackScriptDelete EventAction = "stackscript_delete"
200 ActionStackScriptUpdate EventAction = "stackscript_update"
201 ActionStackScriptPublicize EventAction = "stackscript_publicize"
202 ActionStackScriptRevise EventAction = "stackscript_revise"
203 ActionTaxIDInvalid EventAction = "tax_id_invalid"
204 ActionTagCreate EventAction = "tag_create"
205 ActionTagDelete EventAction = "tag_delete"
206 ActionTFADisabled EventAction = "tfa_disabled"
207 ActionTFAEnabled EventAction = "tfa_enabled"
208 ActionTicketAttachmentUpload EventAction = "ticket_attachment_upload"
209 ActionTicketCreate EventAction = "ticket_create"
210 ActionTicketUpdate EventAction = "ticket_update"
211 ActionTokenCreate EventAction = "token_create"
212 ActionTokenDelete EventAction = "token_delete"
213 ActionTokenUpdate EventAction = "token_update"
214 ActionUserCreate EventAction = "user_create"
215 ActionUserDelete EventAction = "user_delete"
216 ActionUserUpdate EventAction = "user_update"
217 ActionUserSSHKeyAdd EventAction = "user_ssh_key_add"
218 ActionUserSSHKeyDelete EventAction = "user_ssh_key_delete"
219 ActionUserSSHKeyUpdate EventAction = "user_ssh_key_update"
220 ActionVLANAttach EventAction = "vlan_attach"
221 ActionVLANDetach EventAction = "vlan_detach"
222 ActionVolumeAttach EventAction = "volume_attach"
223 ActionVolumeClone EventAction = "volume_clone"
224 ActionVolumeCreate EventAction = "volume_create"
225 ActionVolumeDelete EventAction = "volume_delete"
226 ActionVolumeUpdate EventAction = "volume_update"
227 ActionVolumeDetach EventAction = "volume_detach"
228 ActionVolumeResize EventAction = "volume_resize"
229 ActionVPCCreate EventAction = "vpc_create"
230 ActionVPCDelete EventAction = "vpc_delete"
231 ActionVPCUpdate EventAction = "vpc_update"
232 ActionVPCSubnetCreate EventAction = "subnet_create"
233 ActionVPCSubnetDelete EventAction = "subnet_delete"
234 ActionVPCSubnetUpdate EventAction = "subnet_update"
235
236 // Deprecated: incorrect spelling,
237 // to be removed in the next major version release.
238 ActionVolumeDelte EventAction = "volume_delete"
239
240 // Deprecated: incorrect spelling,
241 // to be removed in the next major version
242 ActionCreateCardUpdated = ActionCreditCardUpdated
243 )
244
245 // EntityType constants start with Entity and include Linode API Event Entity Types
246 type EntityType string
247
248 // EntityType constants are the entities an Event can be related to.
249 const (
250 EntityAccount EntityType = "account"
251 EntityBackups EntityType = "backups"
252 EntityCommunity EntityType = "community"
253 EntityDatabase EntityType = "database"
254 EntityDisk EntityType = "disk"
255 EntityDomain EntityType = "domain"
256 EntityTransfer EntityType = "entity_transfer"
257 EntityFirewall EntityType = "firewall"
258 EntityImage EntityType = "image"
259 EntityIPAddress EntityType = "ipaddress"
260 EntityLinode EntityType = "linode"
261 EntityLongview EntityType = "longview"
262 EntityManagedService EntityType = "managed_service"
263 EntityNodebalancer EntityType = "nodebalancer"
264 EntityOAuthClient EntityType = "oauth_client"
265 EntityPlacementGroup EntityType = "placement_group"
266 EntityProfile EntityType = "profile"
267 EntityStackscript EntityType = "stackscript"
268 EntityTag EntityType = "tag"
269 EntityTicket EntityType = "ticket"
270 EntityToken EntityType = "token"
271 EntityUser EntityType = "user"
272 EntityUserSSHKey EntityType = "user_ssh_key"
273 EntityVolume EntityType = "volume"
274 EntityVPC EntityType = "vpc"
275 EntityVPCSubnet EntityType = "subnet"
276 )
277
278 // EventStatus constants start with Event and include Linode API Event Status values
279 type EventStatus string
280
281 // EventStatus constants reflect the current status of an Event
282 const (
283 EventFailed EventStatus = "failed"
284 EventFinished EventStatus = "finished"
285 EventNotification EventStatus = "notification"
286 EventScheduled EventStatus = "scheduled"
287 EventStarted EventStatus = "started"
288 EventCanceled EventStatus = "canceled"
289 )
290
291 // EventEntity provides detailed information about the Event's
292 // associated entity, including ID, Type, Label, and a URL that
293 // can be used to access it.
294 type EventEntity struct {
295 // ID may be a string or int, it depends on the EntityType
296 ID any `json:"id"`
297 Label string `json:"label"`
298 Type EntityType `json:"type"`
299 Status string `json:"status"`
300 URL string `json:"url"`
301 }
302
303 // UnmarshalJSON implements the json.Unmarshaler interface
304 func (i *Event) UnmarshalJSON(b []byte) error {
305 type Mask Event
306
307 p := struct {
308 *Mask
309
310 Created *parseabletime.ParseableTime `json:"created"`
311 TimeRemaining json.RawMessage `json:"time_remaining"`
312 NotBefore *parseabletime.ParseableTime `json:"not_before"`
313 StartTime *parseabletime.ParseableTime `json:"start_time"`
314 CompleteTime *parseabletime.ParseableTime `json:"complete_time"`
315 }{
316 Mask: (*Mask)(i),
317 }
318
319 if err := json.Unmarshal(b, &p); err != nil {
320 return err
321 }
322
323 i.Created = (*time.Time)(p.Created)
324 i.TimeRemaining = duration.UnmarshalTimeRemaining(p.TimeRemaining)
325 i.NotBefore = (*time.Time)(p.NotBefore)
326 i.StartTime = (*time.Time)(p.StartTime)
327 i.CompleteTime = (*time.Time)(p.CompleteTime)
328
329 return nil
330 }
331
332 // ListEvents gets a collection of Event objects representing actions taken
333 // on the Account. The Events returned depend on the token grants and the grants
334 // of the associated user.
335 func (c *Client) ListEvents(ctx context.Context, opts *ListOptions) ([]Event, error) {
336 return getPaginatedResults[Event](ctx, c, "account/events", opts)
337 }
338
339 // GetEvent gets the Event with the Event ID
340 func (c *Client) GetEvent(ctx context.Context, eventID int) (*Event, error) {
341 e := formatAPIPath("account/events/%d", eventID)
342 return doGETRequest[Event](ctx, c, e)
343 }
344
345 // MarkEventRead marks a single Event as read.
346 //
347 // Deprecated: `MarkEventRead` is a deprecated API, please consider using `MarkEventsSeen` instead.
348 // Please note that the `MarkEventsSeen` API functions differently and will mark all events up to and
349 // including the referenced event-id as "seen" rather than individual events.
350 func (c *Client) MarkEventRead(ctx context.Context, event *Event) error {
351 e := formatAPIPath("account/events/%d/read", event.ID)
352 return doPOSTRequestNoRequestResponseBody(ctx, c, e)
353 }
354
355 // MarkEventsSeen marks all Events up to and including this Event by ID as seen.
356 func (c *Client) MarkEventsSeen(ctx context.Context, event *Event) error {
357 e := formatAPIPath("account/events/%d/seen", event.ID)
358 return doPOSTRequestNoRequestResponseBody(ctx, c, e)
359 }
360