meowing.zip / iceshrimp.net
a fork of iceshrimp.net but a tweaked frontend to my personal liking. waow
fediverse social-media social iceshrimp fedi
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

[backend/web] Add doc comments for Admin endpoints

authored by

pancakes and committed by
Iceshrimp development a6925bbd 04c7a3b5

+218 -1
+218 -1
Iceshrimp.Backend/Controllers/Web/AdminController.cs
··· 46 46 EventService eventSvc 47 47 ) : ControllerBase 48 48 { 49 + /// <summary> 50 + /// Generate invite code 51 + /// </summary> 52 + /// <remarks> 53 + /// Generate an invite code which can be used to register an account if <c>[Security] Registrations = Invite</c>. 54 + /// </remarks> 55 + /// <response code="200">Generated invite code</response> 49 56 [HttpPost("invites/generate")] 50 57 [Produces(MediaTypeNames.Application.Json)] 51 58 [ProducesResults(HttpStatusCode.OK)] ··· 66 73 return new InviteResponse { Code = invite.Code }; 67 74 } 68 75 76 + /// <summary> 77 + /// Revoke invite code 78 + /// </summary> 79 + /// <remarks> 80 + /// Revoke an invite code so it can no longer be used to register accounts. 81 + /// </remarks> 82 + /// <param name="code">Invite code to revoke</param> 69 83 [HttpPost("invites/{code}/revoke")] 70 84 [ProducesResults(HttpStatusCode.OK)] 71 85 public async Task<OkResult> RevokeInvite(string code) ··· 74 88 return Ok(); 75 89 } 76 90 91 + /// <summary> 92 + /// Reset user password 93 + /// </summary> 94 + /// <remarks> 95 + /// Reset a user's password to a provided value so they can regain access to their account. 96 + /// </remarks> 97 + /// <param name="id">The user's ID</param> 98 + /// <param name="request">Reset password request</param> 99 + /// <response code="400">Password must be at least 8 characters long</response> 77 100 [HttpPost("users/{id}/reset-password")] 78 101 [Produces(MediaTypeNames.Application.Json)] 79 102 [Consumes(MediaTypeNames.Application.Json)] ··· 91 114 await db.SaveChangesAsync(); 92 115 } 93 116 117 + /// <summary> 118 + /// Reset two-factor authentication 119 + /// </summary> 120 + /// <remarks> 121 + /// Reset a user's two-factor authentication so they can regain access to their account. 122 + /// </remarks> 123 + /// <param name="id">The user's ID</param> 94 124 [HttpPost("users/{id}/reset-2fa")] 95 125 [Produces(MediaTypeNames.Application.Json)] 96 126 [ProducesResults(HttpStatusCode.OK)] ··· 107 137 await db.SaveChangesAsync(); 108 138 } 109 139 140 + /// <summary> 141 + /// List allowed instances 142 + /// </summary> 143 + /// <remarks>If <c>[Security] FederationMode = AllowList</c>, returns the list of instances which are allowed to federate.</remarks> 144 + /// <param name="limit">Pagination limit</param> 145 + /// <param name="offset">Pagination offset</param> 146 + /// <response code="400">Federation mode is set to blocklist.</response> 110 147 [HttpGet("instances/allowed")] 111 148 [ProducesResults(HttpStatusCode.OK)] 112 149 [ProducesErrors(HttpStatusCode.BadRequest)] ··· 124 161 return await q.ToListAsync(); 125 162 } 126 163 164 + /// <summary> 165 + /// List blocked instances 166 + /// </summary> 167 + /// <remarks>If <c>[Security] FederationMode = BlockList</c>, returns the list of instances which are blocked from federating and the block reasons.</remarks> 168 + /// <param name="limit">Pagination limit</param> 169 + /// <param name="offset">Pagination offset</param> 170 + /// <response code="400">Federation mode is set to allowlist.</response> 127 171 [HttpGet("instances/blocked")] 128 172 [ProducesResults(HttpStatusCode.OK)] 129 173 [ProducesErrors(HttpStatusCode.BadRequest)] ··· 141 185 return await q.ToListAsync(); 142 186 } 143 187 188 + /// <summary> 189 + /// Import allowed instances 190 + /// </summary> 191 + /// <remarks> 192 + /// Import a list of instances that are allowed to federate if <c>[Security] FederationMode = AllowList</c>. 193 + /// <code>instance</code> 194 + /// </remarks> 195 + /// <param name="file">CSV file containing a list of instances</param> 196 + /// <response code="400">Federation mode is set to blocklist.</response> 144 197 [HttpPost("instances/allowed/import")] 145 198 [ProducesResults(HttpStatusCode.Accepted)] 146 199 [ProducesErrors(HttpStatusCode.BadRequest)] ··· 178 231 return Accepted(); 179 232 } 180 233 234 + /// <summary> 235 + /// Import blocked instances 236 + /// </summary> 237 + /// <remarks> 238 + /// Import a list of instances that are not allowed to federate if <c>[Security] FederationMode = BlockList</c>. 239 + /// <code>instance,reason</code> 240 + /// </remarks> 241 + /// <param name="file">CSV file containing a list of instances and reasons</param> 242 + /// <response code="400">Federation mode is set to allowlist.</response> 181 243 [HttpPost("instances/blocked/import")] 182 244 [ProducesResults(HttpStatusCode.Accepted)] 183 245 [ProducesErrors(HttpStatusCode.BadRequest)] ··· 215 277 return Accepted(); 216 278 } 217 279 218 - 280 + /// <summary> 281 + /// Allow instance 282 + /// </summary> 283 + /// <remarks> 284 + /// Adds or updates an instance in the allow list. It is recommended to use the root domain (e.g. <c>example.org</c> instead of <c>shrimp.example.org</c>) when adding new instances. 285 + /// </remarks> 286 + /// <param name="host" example="example.org">Instance domain name</param> 287 + /// <param name="imported">Imported flag</param> 288 + /// <response code="400">Federation mode is set to blocklist.</response> 219 289 [HttpPost("instances/{host}/allow")] 220 290 [ProducesResults(HttpStatusCode.OK)] 221 291 [ProducesErrors(HttpStatusCode.BadRequest)] ··· 240 310 await db.SaveChangesAsync(); 241 311 } 242 312 313 + /// <summary> 314 + /// Block instance 315 + /// </summary> 316 + /// <remarks> 317 + /// Adds or updates an instance in the block list. It is recommended to use the root domain (e.g. <c>example.org</c> instead of <c>shrimp.example.org</c>) when adding new instances. 318 + /// </remarks> 319 + /// <param name="host" example="example.org">Instance domain name</param> 320 + /// <param name="imported">Imported flag</param> 321 + /// <param name="reason">Reason for the block</param> 322 + /// <response code="400">Federation mode is set to allowlist.</response> 243 323 [HttpPost("instances/{host}/block")] 244 324 [ProducesResults(HttpStatusCode.OK)] 245 325 [ProducesErrors(HttpStatusCode.BadRequest)] ··· 269 349 await db.SaveChangesAsync(); 270 350 } 271 351 352 + /// <summary> 353 + /// Disallow instance 354 + /// </summary> 355 + /// <remarks> 356 + /// Removes an instance from the allow list. 357 + /// </remarks> 358 + /// <param name="host" example="example.org">Instance domain name</param> 272 359 [HttpPost("instances/{host}/disallow")] 273 360 [ProducesResults(HttpStatusCode.OK)] 274 361 public async Task DisallowInstance(string host) ··· 279 366 await db.AllowedInstances.Where(p => p.Host == host.ToPunycodeLower()).ExecuteDeleteAsync(); 280 367 } 281 368 369 + /// <summary> 370 + /// Remove bubble instance 371 + /// </summary> 372 + /// <remarks> 373 + /// Removes an instance from the bubble. 374 + /// </remarks> 375 + /// <param name="host" example="example.org">Instance domain name</param> 282 376 [HttpPost("instances/{host}/debubble")] 283 377 [ProducesResults(HttpStatusCode.OK)] 284 378 public async Task DebubbleInstance(string host) ··· 287 381 if (res > 0) eventSvc.RaiseBubbleInstanceRemoved(new BubbleInstance { Host = host }); 288 382 } 289 383 384 + /// <summary> 385 + /// Unblock instance 386 + /// </summary> 387 + /// <remarks> 388 + /// Removes an instance from the block list. 389 + /// </remarks> 390 + /// <param name="host" example="example.org">Instance domain name</param> 290 391 [HttpPost("instances/{host}/unblock")] 291 392 [ProducesResults(HttpStatusCode.OK)] 292 393 public async Task UnblockInstance(string host) ··· 297 398 await db.BlockedInstances.Where(p => p.Host == host.ToPunycodeLower()).ExecuteDeleteAsync(); 298 399 } 299 400 401 + /// <summary> 402 + /// Override instance status 403 + /// </summary> 404 + /// <param name="host" example="example.org">Instance domain name</param> 405 + /// <param name="state">State the instance should be set to</param> 300 406 [HttpPost("instances/{host}/force-state/{state}")] 301 407 [ProducesResults(HttpStatusCode.OK)] 302 408 [ProducesErrors(HttpStatusCode.NotFound)] ··· 323 429 await db.SaveChangesAsync(); 324 430 } 325 431 432 + /// <summary> 433 + /// Retry job 434 + /// </summary> 435 + /// <param name="id">The job's ID</param> 326 436 [HttpPost("queue/jobs/{id::guid}/retry")] 327 437 [ProducesResults(HttpStatusCode.OK)] 328 438 [ProducesErrors(HttpStatusCode.BadRequest, HttpStatusCode.NotFound)] ··· 334 444 await queueSvc.RetryJobAsync(job); 335 445 } 336 446 447 + /// <summary> 448 + /// Retry all jobs 449 + /// </summary> 450 + /// <remarks>Retry all jobs in a queue.</remarks> 451 + /// <param name="queue">Name of the queue</param> 337 452 [HttpPost("queue/{queue}/retry-all")] 338 453 [ProducesResults(HttpStatusCode.OK)] 339 454 public async Task RetryFailedJobs(string queue) ··· 346 461 await queueSvc.RetryJobAsync(job); 347 462 } 348 463 464 + /// <summary> 465 + /// Retry jobs 466 + /// </summary> 467 + /// <remarks>Retry a range of jobs in a queue.</remarks> 468 + /// <param name="queue">Name of the queue</param> 469 + /// <param name="from">Inclusive range start</param> 470 + /// <param name="to">Inclusive range end</param> 349 471 [HttpPost("queue/{queue}/retry-range/{from::guid}/{to::guid}")] 350 472 [ProducesResults(HttpStatusCode.OK)] 351 473 public async Task RetryRange(string queue, Guid from, Guid to) ··· 359 481 await queueSvc.RetryJobAsync(job); 360 482 } 361 483 484 + /// <summary> 485 + /// Abandon job 486 + /// </summary> 487 + /// <param name="id">The job's ID</param> 362 488 [HttpPost("queue/jobs/{id::guid}/abandon")] 363 489 [ProducesResults(HttpStatusCode.OK)] 364 490 [ProducesErrors(HttpStatusCode.BadRequest, HttpStatusCode.NotFound)] ··· 370 496 await queueSvc.AbandonJobAsync(job); 371 497 } 372 498 499 + /// <summary> 500 + /// List relays 501 + /// </summary> 502 + /// <remarks>Returns a list of ActivityPub relays and their statuses.</remarks> 373 503 [HttpGet("relays")] 374 504 [ProducesResults(HttpStatusCode.OK)] 375 505 public async Task<List<RelaySchemas.RelayResponse>> GetRelays() ··· 385 515 .ToList()); 386 516 } 387 517 518 + /// <summary> 519 + /// Add relay 520 + /// </summary> 521 + /// <remarks>Adds an ActivityPub relay.</remarks> 522 + /// <param name="rq">Relay request</param> 388 523 [HttpPost("relays")] 389 524 [ProducesResults(HttpStatusCode.OK)] 390 525 public async Task SubscribeToRelay(RelaySchemas.RelayRequest rq) ··· 392 527 await relaySvc.SubscribeToRelayAsync(rq.Inbox); 393 528 } 394 529 530 + /// <summary> 531 + /// Remove relay 532 + /// </summary> 533 + /// <param name="id">The relay's ID.</param> 395 534 [HttpDelete("relays/{id}")] 396 535 [ProducesResults(HttpStatusCode.OK)] 397 536 [ProducesErrors(HttpStatusCode.NotFound)] ··· 402 541 await relaySvc.UnsubscribeFromRelayAsync(relay); 403 542 } 404 543 544 + /// <summary> 545 + /// Prune expired media 546 + /// </summary> 547 + /// <remarks>Delete all files from the Drive that have expired.</remarks> 405 548 [HttpPost("drive/prune-expired-media")] 406 549 [ProducesResults(HttpStatusCode.OK)] 407 550 public async Task PruneExpiredMedia([FromServices] IServiceScopeFactory factory) ··· 410 553 await new MediaCleanupTask().InvokeAsync(scope.ServiceProvider); 411 554 } 412 555 556 + /// <summary> 557 + /// Run cron task 558 + /// </summary> 559 + /// <param name="id">The task's ID.</param> 413 560 [HttpPost("tasks/{id}/run")] 414 561 [ProducesResults(HttpStatusCode.OK)] 415 562 [ProducesErrors(HttpStatusCode.NotFound)] ··· 426 573 CancellationToken.None); 427 574 } 428 575 576 + /// <summary> 577 + /// List policies 578 + /// </summary> 579 + /// <remarks> 580 + /// Returns a list of available policy names. Policies are Iceshrimp.NET's message rewrite facility. They allow instances admins to modify incoming notes as they are federated. 581 + /// </remarks> 429 582 [HttpGet("policy")] 430 583 [ProducesResults(HttpStatusCode.OK)] 431 584 public async Task<List<string>> GetAvailablePolicies() => await policySvc.GetAvailablePoliciesAsync(); 432 585 586 + /// <summary> 587 + /// Get policy 588 + /// </summary> 589 + /// <remarks>Returns the configuration for a policy.</remarks> 590 + /// <param name="name" example="WordRejectPolicy">The policy's name</param> 591 + /// <response code="200">The policy's configuration</response> 433 592 [HttpGet("policy/{name}")] 434 593 [ProducesResults(HttpStatusCode.OK)] 435 594 [ProducesErrors(HttpStatusCode.NotFound)] ··· 439 598 return await policySvc.GetConfigurationAsync(name, raw) ?? throw GracefulException.NotFound("Policy not found"); 440 599 } 441 600 601 + /// <summary> 602 + /// Set policy 603 + /// </summary> 604 + /// <remarks>Updates the configuration of a policy.</remarks> 605 + /// <param name="name" example="WordRejectPolicy">The policy's name</param> 606 + /// <param name="body">Policy configuration</param> 442 607 [HttpPut("policy/{name}")] 443 608 [ProducesResults(HttpStatusCode.OK)] 444 609 [ProducesErrors(HttpStatusCode.BadRequest, HttpStatusCode.NotFound)] ··· 459 624 await policySvc.UpdateAsync(); 460 625 } 461 626 627 + /// <summary> 628 + /// Get note activity 629 + /// </summary> 630 + /// <remarks> 631 + /// Returns the ActivityPub representation of a local note. 632 + /// </remarks> 633 + /// <param name="id">The note's ID</param> 634 + /// <response code="200">Note Activity</response> 462 635 [UseNewtonsoftJson] 463 636 [HttpGet("activities/notes/{id}")] 464 637 [OverrideResultType<ASNote>] ··· 475 648 return rendered.Compact() ?? throw new Exception("Failed to compact JSON-LD payload"); 476 649 } 477 650 651 + /// <summary> 652 + /// Get announce activity 653 + /// </summary> 654 + /// <remarks> 655 + /// Returns the ActivityPub representation of a local renote. 656 + /// </remarks> 657 + /// <param name="id">The renote's ID</param> 658 + /// <response code="200">Announce Activity</response> 478 659 [UseNewtonsoftJson] 479 660 [HttpGet("activities/notes/{id}/activity")] 480 661 [OverrideResultType<ASAnnounce>] ··· 501 682 .Compact(); 502 683 } 503 684 685 + /// <summary> 686 + /// Get person activity by ID 687 + /// </summary> 688 + /// <remarks> 689 + /// Returns the ActivityPub representation of a user. 690 + /// </remarks> 691 + /// <param name="id">The user's ID</param> 692 + /// <response code="200">Person Activity</response> 504 693 [UseNewtonsoftJson] 505 694 [HttpGet("activities/users/{id}")] 506 695 [OverrideResultType<ASActor>] ··· 512 701 return await apController.GetUser(id); 513 702 } 514 703 704 + /// <summary> 705 + /// Get featured notes activity 706 + /// </summary> 707 + /// <remarks> 708 + /// Returns the ActivityPub representation of a local user's pinned notes. 709 + /// </remarks> 710 + /// <param name="id">The user's ID</param> 711 + /// <response code="200">OrderedCollection Activity</response> 515 712 [UseNewtonsoftJson] 516 713 [HttpGet("activities/users/{id}/collections/featured")] 517 714 [OverrideResultType<ASOrderedCollection>] ··· 522 719 return await apController.GetUserFeatured(id); 523 720 } 524 721 722 + /// <summary> 723 + /// Get person activity by username 724 + /// </summary> 725 + /// <remarks> 726 + /// Returns the ActivityPub representation of a user. 727 + /// </remarks> 728 + /// <param name="acct" example="username@example.org">The user's username</param> 729 + /// <response code="200">Person Activity</response> 525 730 [UseNewtonsoftJson] 526 731 [HttpGet("activities/users/@{acct}")] 527 732 [OverrideResultType<ASActor>] ··· 532 737 return await apController.GetUserByUsername(acct); 533 738 } 534 739 740 + /// <summary> 741 + /// Get activity 742 + /// </summary> 743 + /// <remarks>Returns an ActivityPub Activity.</remarks> 744 + /// <param name="uri">The object's URI</param> 745 + /// <param name="userId">The viewing user's ID (if the Activity is not public)</param> 535 746 [UseNewtonsoftJson] 536 747 [HttpGet("activities/fetch")] 537 748 [OverrideResultType<ASObject>] ··· 545 756 return Ok(LdHelpers.Compact(activity)); 546 757 } 547 758 759 + /// <summary> 760 + /// Get raw activity 761 + /// </summary> 762 + /// <remarks>Returns an ActivityPub Activity.</remarks> 763 + /// <param name="uri">The object's URI</param> 764 + /// <param name="userId">The viewing user's ID (if the Activity is not public)</param> 548 765 [UseNewtonsoftJson] 549 766 [HttpGet("activities/fetch-raw")] 550 767 [OverrideResultType<ASObject>]