@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Write some basic "dealing with Conduit changes" documentation
Summary:
Ref T9980. No magic here, just write a little bit about how to find outdated callers. Update the technical doc.
Also:
- Fix an unrelated bug where you couldn't leave comments if an object had missing, required, custom fields.
- Restore the ConduitConnectionLog table so `bin/storage adjust` doesn't complain.
Test Plan: Read docs.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T9980
Differential Revision: https://secure.phabricator.com/D14784
+97
-45
+2
src/__phutil_library_map__.php
+2
src/__phutil_library_map__.php
···
1883
1883
'PhabricatorConduitAPIController' => 'applications/conduit/controller/PhabricatorConduitAPIController.php',
1884
1884
'PhabricatorConduitApplication' => 'applications/conduit/application/PhabricatorConduitApplication.php',
1885
1885
'PhabricatorConduitCertificateToken' => 'applications/conduit/storage/PhabricatorConduitCertificateToken.php',
1886
+
'PhabricatorConduitConnectionLog' => 'applications/conduit/storage/PhabricatorConduitConnectionLog.php',
1886
1887
'PhabricatorConduitConsoleController' => 'applications/conduit/controller/PhabricatorConduitConsoleController.php',
1887
1888
'PhabricatorConduitController' => 'applications/conduit/controller/PhabricatorConduitController.php',
1888
1889
'PhabricatorConduitDAO' => 'applications/conduit/storage/PhabricatorConduitDAO.php',
···
5996
5997
'PhabricatorConduitAPIController' => 'PhabricatorConduitController',
5997
5998
'PhabricatorConduitApplication' => 'PhabricatorApplication',
5998
5999
'PhabricatorConduitCertificateToken' => 'PhabricatorConduitDAO',
6000
+
'PhabricatorConduitConnectionLog' => 'PhabricatorConduitDAO',
5999
6001
'PhabricatorConduitConsoleController' => 'PhabricatorConduitController',
6000
6002
'PhabricatorConduitController' => 'PhabricatorController',
6001
6003
'PhabricatorConduitDAO' => 'PhabricatorLiskDAO',
+26
src/applications/conduit/storage/PhabricatorConduitConnectionLog.php
+26
src/applications/conduit/storage/PhabricatorConduitConnectionLog.php
···
1
+
<?php
2
+
3
+
final class PhabricatorConduitConnectionLog extends PhabricatorConduitDAO {
4
+
5
+
protected $client;
6
+
protected $clientVersion;
7
+
protected $clientDescription;
8
+
protected $username;
9
+
10
+
protected function getConfiguration() {
11
+
return array(
12
+
self::CONFIG_COLUMN_SCHEMA => array(
13
+
'client' => 'text255?',
14
+
'clientVersion' => 'text255?',
15
+
'clientDescription' => 'text255?',
16
+
'username' => 'text255?',
17
+
),
18
+
self::CONFIG_KEY_SCHEMA => array(
19
+
'key_created' => array(
20
+
'columns' => array('dateCreated'),
21
+
),
22
+
),
23
+
) + parent::getConfiguration();
24
+
}
25
+
26
+
}
+1
src/applications/transactions/editengine/PhabricatorEditEngine.php
+1
src/applications/transactions/editengine/PhabricatorEditEngine.php
···
1431
1431
$editor = $object->getApplicationTransactionEditor()
1432
1432
->setActor($viewer)
1433
1433
->setContinueOnNoEffect($request->isContinueRequest())
1434
+
->setContinueOnMissingFields(true)
1434
1435
->setContentSourceFromRequest($request)
1435
1436
->setIsPreview($is_preview);
1436
1437
+17
-45
src/docs/tech/conduit.diviner
+17
-45
src/docs/tech/conduit.diviner
···
3
3
4
4
Technical overview of the Conduit API.
5
5
6
-
= Overview =
7
-
8
-
Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on
9
-
the internet.
10
-
11
-
Theoretically, it provides an API to Phabricator so external scripts (including
12
-
scripts written in other languages) can interface with the applications in the
13
-
Phabricator suite. It technically does this, sort of, but it is unstable and
14
-
incomplete so you should keep your expectations very low if you choose to build
15
-
things on top of it.
6
+
Overview
7
+
========
16
8
17
-
NOTE: Hopefully, this should improve over time, but making Conduit more robust
18
-
isn't currently a major project priority because there isn't much demand for it
19
-
outside of internal scripts. If you want to use Conduit to build things on top
20
-
of Phabricator, let us know so we can adjust priorities.
21
-
22
-
Conduit provides an authenticated HTTP API for Phabricator. It is informal and
23
-
extremely simple: you post a JSON blob and you get a JSON blob back. You can
24
-
access Conduit in PHP with @{class@libphutil:ConduitClient}, or in any language
25
-
by executing `arc call-conduit method` (see `arc help call-conduit` for
26
-
more information). You can see and test available methods at `/conduit/` in
27
-
the web interface.
28
-
29
-
Arcanist is implemented using Conduit, and @{class:PhabricatorBot} is
30
-
intended as a practical example of how to write a program which interfaces with
31
-
Phabricator over Conduit.
32
-
33
-
= Class Relationships =
9
+
Conduit is the HTTP API for Phabricator. It is roughly JSON-RPC: you usually
10
+
pass a JSON blob, and usually get a JSON blob back, although both call and
11
+
result formats are flexible in some cases.
34
12
35
-
The primary Conduit workflow is exposed at `/api/`, which routes to
36
-
@{class:PhabricatorConduitAPIController}. This controller builds a
37
-
@{class:ConduitAPIRequest} representing authentication information and POST
38
-
parameters, instantiates an appropriate subclass of @{class:ConduitAPIMethod},
39
-
and passes the request to it. Subclasses of @{class:ConduitAPIMethod} implement
40
-
the actual methods which Conduit exposes.
13
+
The easiest way to begin exploring Conduit is by visiting {nav Conduit} in the
14
+
web UI. The application provides an API console which you can use to explore
15
+
available methods, make calls, read documentation, and see examples.
41
16
42
-
Conduit calls which fail throw @{class:ConduitException}, which the controller
43
-
handles.
17
+
The API console has details about how to construct calls and generate API
18
+
tokens for authentication.
44
19
45
-
There is a web interface for viewing and testing Conduit called the "Conduit
46
-
Console", implemented by @{class:PhabricatorConduitConsoleController} at
47
-
`/conduit/`.
20
+
The three primary ways to make Conduit calls are:
48
21
49
-
A log of connections and calls is stored in
50
-
@{class:PhabricatorConduitMethodCallLog}, and can be accessed on the web via
51
-
@{class:PhabricatorConduitLogController} at `/conduit/log/`.
22
+
- `arc call-conduit`: You can use this `arc` command to execute low-level
23
+
Conduit calls.
24
+
- `curl`: You can format a call with basic HTTP parameters and cURL.
25
+
- `ConduitClient`:
52
26
53
-
Conduit provides a token-based handshake mechanism used by
54
-
`arc install-certificate` at `/conduit/token/`, implemented by
55
-
@{class:PhabricatorConduitTokenController} which stores generated tokens using
56
-
@{class:PhabricatorConduitCertificateToken}.
27
+
There are also clients available in other languages. The Arcanist CLI client
28
+
for Phabricator is implemented over Conduit.
+51
src/docs/user/field/conduit_changes.diviner
+51
src/docs/user/field/conduit_changes.diviner
···
1
+
@title Managing Conduit Changes
2
+
@group fieldmanual
3
+
4
+
Help with managing Conduit API changes.
5
+
6
+
Overview
7
+
========
8
+
9
+
Many parts of the Conduit API are stable, but some parts are subject to change.
10
+
For example, when we write a new application, it usually adds several new API
11
+
methods and may update older methods.
12
+
13
+
This document discusses API stability and how to minimize disruption when
14
+
transitionig between API versions.
15
+
16
+
17
+
Method Statuses
18
+
===============
19
+
20
+
Methods have one of three statuses:
21
+
22
+
- **Unstable**: This is a new or experimental method which is subject to
23
+
change. You may call these methods to get access to recently released
24
+
features, but should expect that you may need to adjust your usage of
25
+
them before they stabilize.
26
+
- **Stable**: This is an established method which generally will not change.
27
+
- **Deprecated**: This method will be removed in a future version of
28
+
Phabricator and callers should cease using it.
29
+
30
+
Normally, a method is deprecated only when it is obsolete or a new, more
31
+
powerful method is available to replace it.
32
+
33
+
34
+
Finding Deprecated Calls
35
+
========================
36
+
37
+
You can identify calls to deprecated methods in {nav Conduit > Call Logs}.
38
+
Use {nav My Deprecated Calls} to find calls to deprecated methods you have
39
+
made, and {nav Deprecated Call Logs} to find deprecated calls by all users.
40
+
41
+
You can also search for calls by specific users. For example, it may be useful
42
+
to serach for any bot accounts you run to make sure they aren't calling
43
+
outdated APIs.
44
+
45
+
The most common cause of calls to deprecated methods is users running very
46
+
old versions of Arcanist. They can normally upgrade by running `arc upgrade`.
47
+
48
+
When the changelogs mention a method deprecation, you can use the call logs
49
+
to identify callers and notify them to upgrade or switch away. When the
50
+
changelogs mention a method removal, you can use the call logs to verify that
51
+
you will not be impacted.